Authenticate

POST {{apiPath}}/directory/v1/authenticate

The POST /authenticate endpoint allows users to generate an access token by providing combinations of valid credentials depending on the authentication type that they specify in the HTTP request body. For more information, refer to Supported credential types.

The request body may include the following fields:

credentials

A mandatory JSON object that describes the authentication method to use to authenticate and provides the appropriate type(s) of credentials for that authentication method.
returnUserAttributes

An optional array of strings that name the attributes from the authenticated user’s entry that should be included in the response. If this is absent or empty, the response will not include any attributes from the target user’s entry. Values in this object may be specific attribute names, or they may also be tokens like "*" (indicating that all user attributes should be included) or "+" (indicating that all operational attributes should be included).
_controls

An optional array of JSON-formatted request controls that can be used when processing the authentication request.

Upon a successful operation, the JSON object in the response body may include the following fields:

resultCode

A mandatory JSON object that contains the following fields:
- value - The integer value for the LDAP result code. This is required.
- name - A name for the LDAP result code. This is optional but recommended.
diagnosticMessage

An optional string field that holds a human-readable message with additional information about the operation.
accessToken

An optional string field that holds an access token that the user can use to authorize subsequent requests. This token may be used in the Authorization header of subsequent requests submitted to the Directory REST API.The access token can be included as a Bearer Token in an HTTP Authorization header in later API HTTP requests.
userAttributes

An optional JSON object field whose contents represent attributes from the authenticated user’s entry. This is included in the response to a successful authentication attempt if the request included the returnUserAttributes field. The attributes are subject to access control restrictions imposed on the target user.
secondsUntilPasswordExpiration

An optional integer field whose value will be the length of time in seconds until the user’s current password will expire. This is only included if the user’s account has a known password expiration time.
mustChangePassword

An optional Boolean field that indicates whether the user will be required to choose a new password before they will be allowed to perform any other operations on the server.
_controls

An optional array of JSON-formatted response controls.

Headers

Authorization Bearer {{accessToken}}

Content-Type application/json

Body

raw ( application/json )

{
    "returnUserAttributes": [
        "*"
    ],
    "credentials": {
        "authenticationType": "password",
        "dn": "uid=jimbob,ou=people,dc=example,dc=com",
        "staticPassword": "password"
    }
}

Example Request

curl --location --globoff '{{apiPath}}/directory/v1/authenticate' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{accessToken}}' \
--data '{
    "returnUserAttributes": [
        "*"
    ],
    "credentials": {
        "authenticationType": "password",
        "dn": "uid=jimbob,ou=people,dc=example,dc=com",
        "staticPassword": "password"
    }
}'

var options = new RestClientOptions("{{apiPath}}/directory/v1/authenticate")
{
  MaxTimeout = -1,
};
var client = new RestClient(options);
var request = new RestRequest("", Method.Post);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("Authorization", "Bearer {{accessToken}}");
var body = @"{" + "\n" +
@"    ""returnUserAttributes"": [" + "\n" +
@"        ""*""" + "\n" +
@"    ]," + "\n" +
@"    ""credentials"": {" + "\n" +
@"        ""authenticationType"": ""password""," + "\n" +
@"        ""dn"": ""uid=jimbob,ou=people,dc=example,dc=com""," + "\n" +
@"        ""staticPassword"": ""password""" + "\n" +
@"    }" + "\n" +
@"}";
request.AddStringBody(body, DataFormat.Json);
RestResponse response = await client.ExecuteAsync(request);
Console.WriteLine(response.Content);

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io"
)

func main() {

  url := "{{apiPath}}/directory/v1/authenticate"
  method := "POST"

  payload := strings.NewReader(`{
    "returnUserAttributes": [
        "*"
    ],
    "credentials": {
        "authenticationType": "password",
        "dn": "uid=jimbob,ou=people,dc=example,dc=com",
        "staticPassword": "password"
    }
}`)

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
    return
  }
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("Authorization", "Bearer {{accessToken}}")

  res, err := client.Do(req)
  if err != nil {
    fmt.Println(err)
    return
  }
  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    fmt.Println(err)
    return
  }
  fmt.Println(string(body))
}

POST /directory/v1/authenticate HTTP/1.1
Host: {{apiPath}}
Content-Type: application/json
Authorization: Bearer {{accessToken}}

{
    "returnUserAttributes": [
        "*"
    ],
    "credentials": {
        "authenticationType": "password",
        "dn": "uid=jimbob,ou=people,dc=example,dc=com",
        "staticPassword": "password"
    }
}

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\n    \"returnUserAttributes\": [\n        \"*\"\n    ],\n    \"credentials\": {\n        \"authenticationType\": \"password\",\n        \"dn\": \"uid=jimbob,ou=people,dc=example,dc=com\",\n        \"staticPassword\": \"password\"\n    }\n}");
Request request = new Request.Builder()
  .url("{{apiPath}}/directory/v1/authenticate")
  .method("POST", body)
  .addHeader("Content-Type", "application/json")
  .addHeader("Authorization", "Bearer {{accessToken}}")
  .build();
Response response = client.newCall(request).execute();

var settings = {
  "url": "{{apiPath}}/directory/v1/authenticate",
  "method": "POST",
  "timeout": 0,
  "headers": {
    "Content-Type": "application/json",
    "Authorization": "Bearer {{accessToken}}"
  },
  "data": JSON.stringify({
    "returnUserAttributes": [
      "*"
    ],
    "credentials": {
      "authenticationType": "password",
      "dn": "uid=jimbob,ou=people,dc=example,dc=com",
      "staticPassword": "password"
    }
  }),
};

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require('request');
var options = {
  'method': 'POST',
  'url': '{{apiPath}}/directory/v1/authenticate',
  'headers': {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer {{accessToken}}'
  },
  body: JSON.stringify({
    "returnUserAttributes": [
      "*"
    ],
    "credentials": {
      "authenticationType": "password",
      "dn": "uid=jimbob,ou=people,dc=example,dc=com",
      "staticPassword": "password"
    }
  })

};
request(options, function (error, response) {
  if (error) throw new Error(error);
  console.log(response.body);
});

import requests
import json

url = "{{apiPath}}/directory/v1/authenticate"

payload = json.dumps({
  "returnUserAttributes": [
    "*"
  ],
  "credentials": {
    "authenticationType": "password",
    "dn": "uid=jimbob,ou=people,dc=example,dc=com",
    "staticPassword": "password"
  }
})
headers = {
  'Content-Type': 'application/json',
  'Authorization': 'Bearer {{accessToken}}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

<?php
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
$request->setUrl('{{apiPath}}/directory/v1/authenticate');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
  'follow_redirects' => TRUE
));
$request->setHeader(array(
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer {{accessToken}}'
));
$request->setBody('{\n    "returnUserAttributes": [\n        "*"\n    ],\n    "credentials": {\n        "authenticationType": "password",\n        "dn": "uid=jimbob,ou=people,dc=example,dc=com",\n        "staticPassword": "password"\n    }\n}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  }
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
    $response->getReasonPhrase();
  }
}
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
}

require "uri"
require "json"
require "net/http"

url = URI("{{apiPath}}/directory/v1/authenticate")

http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["Authorization"] = "Bearer {{accessToken}}"
request.body = JSON.dump({
  "returnUserAttributes": [
    "*"
  ],
  "credentials": {
    "authenticationType": "password",
    "dn": "uid=jimbob,ou=people,dc=example,dc=com",
    "staticPassword": "password"
  }
})

response = http.request(request)
puts response.read_body

let parameters = "{\n    \"returnUserAttributes\": [\n        \"*\"\n    ],\n    \"credentials\": {\n        \"authenticationType\": \"password\",\n        \"dn\": \"uid=jimbob,ou=people,dc=example,dc=com\",\n        \"staticPassword\": \"password\"\n    }\n}"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "{{apiPath}}/directory/v1/authenticate")!,timeoutInterval: Double.infinity)
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
request.addValue("Bearer {{accessToken}}", forHTTPHeaderField: "Authorization")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
}

task.resume()

Example Response

200 OK

{
    "resultCode": {
        "value": 0,
        "name": "success"
    },
    "userAttributes": {
        "_dn": "uid=jimbob,ou=People,dc=example,dc=com",
        "objectClass": [
            "top",
            "person",
            "organizationalPerson",
            "inetOrgPerson"
        ],
        "sn": [
            "Bob"
        ],
        "cn": [
            "Jim Bob"
        ],
        "givenName": [
            "Jim"
        ],
        "uid": [
            "jimbob"
        ]
    },
    "accessToken": "VW5A..."
}

PingDirectory API Reference

Authenticate

Headers

Body

Example Request

Example Response