Requesters can authenticate using any of two authentication types, and the requester may have either a privileged or unprivileged identity that determines the activity scope.

Authentication types

The Directory REST API supports the following authentication types:

Basic authentication

Requests are authenticated using a username and password or an encoded API token contained in the Authorization header. The user credentials can be collected interactively from the user, or they can represent the client itself.

Here is a sample of a request using an API token:
```
GET /directory/v1/uid=lindajones,ou=people,dc=example,dc=com HTTP/1.1
  
  Authorization: Basic dWlkPXVzZXIuMCxvdT1wZW9wbGUsZGM9ZXhhbXBsZSxkYz1jb206cGFzc3dvcmQ=
```
Bearer token

Requests are authenticated using an access token contained in the Authorization header. The access token is obtained through an authorization server, such as PingFederate. Here is a sample:
```
GET /directory/v1/uid=lindajones,ou=people,dc=example,dc=com HTTP/1.1
  Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtp...
```
When bearer token authentication is used, the access token used must include a scope that the directory service is configured to accept. Additionally, the directory service may be configured to require that the access token include a specific audience claim.

Access control

Requests to the Directory REST API with a given user is similar to making an LDAP request with the same user, which are subject to the same ACI restrictions. Authenticated users can have full or partial access to the Directory service based on the permissions allowed for that user.

Note: For security reasons, the PingDirectory REST API never returns the userPassword or authPassword properties in a response. For example, if you set a user’s password using PUT with "userPassword": ["passw0rd"], the response does not show the userPassword property or its value. Likewise, if you run a GET request with includeAttribute = userPassword, the response does not include the userPassword property or its value.

Create the request

The following information illustrates how to construct a typical API request.

Request header

The API request header contains the authentication information you must provide to make a call to any Directory REST API resource. The Authorization parameter takes the user credentials or the full bearer token as its value, which contains the authorization information needed to access the requested resource.

The following sample shows the API request header (-H 'Authorization: Bearer) with a base64url-encoded bearer token as its parameter value.

curl -X "GET" "https://<server>/directory/v1/{dn}" \
     -H 'Content-Type: application/json' \
     -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'

The request header also shows an additional parameter or note:

Content-Type

In the header of a PATCH, PUT, or POST request, this parameter identifies the media type of the request data sent to the server. For most Directory API calls, the Content-Type is application/json.

Request body

The API request body for POST, PATCH, or PUT requests provides the attribute values needed to complete the create or update operation. For example, to update an LDAP entry, the PUT operation requires values for the attr1 and attr2 attributes in the request body:

{
  "attr1": "value1",
  "attr2": "value2"
}