--- title: Getting Started description: 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. component: pingdirectory page_id: pingdirectory:directory:getting-started canonical_url: https://developer.pingidentity.com/pingdirectory/directory/getting-started.html section_ids: authentication-types: Authentication types access-control: Access control create-the-request: Create the request request-header: Request header request-body: Request body --- # Getting Started 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: ```none GET /directory/v1/uid=lindajones,ou=people,dc=example,dc=com HTTP/1.1 Authorization: Basic dWlkPXVzZXIuMCxvdT1wZW9wbGUsZGM9ZXhhbXBsZSxkYz1jb206cGFzc3dvcmQ= [source] ``` * **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: ```none GET /directory/v1/uid=lindajones,ou=people,dc=example,dc=com HTTP/1.1 Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtp... [source] ``` 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. You can define ACIs in PingDirectory that map to specific scopes. When users make requests to Directory REST API endpoints using OAuth 2.0 bearer tokens that include configured scopes, PingDirectory can apply the ACIs associated with those scopes and grant the appropriate permissions. ## Access control To help isolate access to admin credentials in authentication workflows, you can use OAuth scopes to enforce access control instructions (ACIs) for users authenticating to specific Directory REST API endpoints. Invoking ACIs using OAuth scopes applies to all REST API endpoints except for the following: * `GET /directory/v1/` * `GET /directory/v1/schemas` * `GET /directory/v1/schemas/{schema}` Making requests to the Directory REST API with a given user is similar to making an LDAP request with the same user and is 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. In other words, scopes are granted dynamically, and are not explicitly stated in the bearer token. The client sending the bearer token in their request is granted permissions by the access token validator at the time of the request. To enable this feature, define the ACIs to include the desired OAuth scopes. The following example allows all authenticated users with the OAuth scope `example:scope` to perform the Get Password Quality Requirements extended operation: ```none (extop="1.3.6.1.4.1.30221.2.6.43")(version 3.0; acl "Extended op permissions for get password quality requirements"; allow (read) oauthscope="example:scope";) [source] ``` Learn more in [Managing the Directory REST API](https://docs.pingidentity.com/pingdirectory/latest/pingdirectory_server_administration_guide/pd_ds_directory_rest_api.html) and [Using OAuth scopes for ACI rules with the REST API](https://docs.pingidentity.com/pingdirectory/latest/pingdirectory_server_administration_guide/pd_ds_use_oauth_scopes_aci_rest_api.html) in the PingDirectory admin guide. | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | | 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. ```none curl -X "GET" "https:///directory/v1/{{dn}}" \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' [source] ``` 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: ```none { "attr1": "value1", "attr2": "value2" } ```