Overview of the client credentials grant

Figure 6 from RFC 6749

The steps are as follows:

• A: The client authenticates with the service provider and requests an access token from the service provider's token endpoint.

• B: The service provider authenticates the client, and if valid, issues an access token.

Authorization request and response

Since the client is requesting on their own behalf, no further authorization is needed.

Access token request

The client makes a POST request to the service provider's token endpoint passing in the following parameters encoded using the application/x-www-form-urlencoded format, as described in Appendix B of the specification:

• grant_type: (Required) The value must be set to client_credentials

• scope: (Optional) A list of space-delimited, case-sensitive strings that represent the scope of the access request

As part of this request, the client application must also authenticate with the service provider. This is typically done using the HTTP basic authentication scheme [RFC 2617], but other authentication schemes may be supported by the service provider as well, such as HTTP digest authentication or public/private key authentication.

An example access token request using HTTP basic authentication looks like:

     POST /token HTTP/1.1
     Host: server.example.com
     Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
     Content-Type: application/x-www-form-urlencoded

     grant_type=client_credentials

Access token response

If the access token request is valid and authorized, the response will contain an access token, an optional refresh token, and other parameters, as described here:

• access_token: (Required) The access token issued by the service provider.

• token_type: (Required) The type of the token issued. This value is case-insensitive.

• expires_in: (Optional) The lifetime of the access token given in seconds. If omitted, the service provider should communicate the expiration time via other means.

• refresh_token: (Optional) A refresh token, which can be used to obtain new access tokens using the refresh token workflow.

• scope: (Conditionally required) A list of space-delimited, case-sensitive strings that represent the scope of the access granted. Required only if the scope granted is different from the scope requested.

An example access token response looks like this:

     HTTP/1.1 200 OK
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "access_token":"2YotnFZFEjr1zCsicMWpAA",
       "token_type":"bearer",
       "expires_in":3600,
       "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
       "example_parameter":"example_value"
     }

Error response

If the access token request fails for any reason, the server will respond with an HTTP 400 (Bad Request) status code including the following properties:

• error: (Required) This is a single error code representing the condition that caused the request to fail. The value must be one of the following:

  • invalid_request: The request is missing a required parameter, includes an unsupported parameter value (other than the grant type), repeats a parameter, includes multiple credentials, utilizes more than one mechanism for authenticating the client, or is otherwise malformed.

  • invalid_client: Client authentication failed for some reason (for example, unknown client, no client authentication included, or unsupported authentication method).

  • invalid_grant: The provided authorization grant or refresh token is invalid, expired, revoked, does not match the redirection URI used in the authorization request, or was issued to another client.

  • unauthorized_client: The authenticated client is not authorized to use this authorization grant type.

  • unsupported_grant_type: The authorization grant type is not supported by the authorization server.

  • invalid_scope: The requested scope is invalid, unknown, malformed, or exceeds the scope granted by the resource owner.

• error_description: (Optional) Human-readable ASCII message providing additional information regarding the error.

• error_uri: (Optional) A URI identifying a human-readable web page providing additional information regarding the error.

An example error response looks like this:

     HTTP/1.1 400 Bad Request
     Content-Type: application/json;charset=UTF-8
     Cache-Control: no-store
     Pragma: no-cache

     {
       "error":"invalid_request"
     }