Grant - Client Credentials

The following is an overview of OAuth 2 authentication with a client credentials grant. For more information on roles and divisions, see Fine-Grained Access Control

The client credentials grant is useful in headless applications that do not have a UI for a user to be able to authenticate, but need to make authenticated API requests. When using the client credentials grant, resources like /api/v2/users/me will not be available because the auth token is not in the context of a user. Since there is no actual user to obtain permissions from, client credentials OAuth clients must be configured with a set of role-division pairs from which to obtain the necessary API access. These role-division pairs are limited to a necessary subset of the ones that the user creating the client id has access.

Follow these steps to obtain an access token using the client credentials method. For a more concise rundown, see Quick Reference.

Navigate to the OAuth admin page (Admin > Integrations > OAuth). The Client ID for each configured OAuth client will be shown in the list. Editing the OAuth client will additionally display the grant type, client secret, and the redirect URIs. Take note of these values as they will be used in the following steps. For help creating a new OAuth client, see Create an OAuth Client.

Make a POST request to the authorization service to get an access token. The request must contain the client ID and client secret in the base 64 encoded Authorization header. For help creating the Authorization header, see How to Use Base 64 Encoding.

POST /oauth/token HTTP/1.1
Host: login.mypurecloud.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic BASE64(<client_id>:<client_secret>)

grant_type=client_credentials

The authorization service returns a JSON response with the token, token type, token expiry time in seconds, and an error string if an error occurred.

{
  "access_token": "token",
  "token_type": "bearer",
  "expires_in": 86400,
  "error": "optional-error-message"
}

Follow these guidelines for using access tokens:

• After authenticating, include a token with every API request.
• Pass the token using the HTTP Authorization header with the bearer keyword, as follows:

GET /api/v2/users HTTP/1.1
Host: api.mypurecloud.com
Content-Type: application/json
Authorization: Bearer token

For a walkthrough of the client credentials grant, see the OAuth Client Credentials Login Flow guide.