POST /oauth/oauth20/token

Returns an OAuth 2.0 token using HTTP POST.

To request an access token using this grant type, the client must have already obtained the Authorization Code from the authorization server. An Authorization Code is a short-lived token issued to the client application by the authorization server upon successful authentication/authorization of an end-user (resource owner). The client application then uses the authorization code to request an access token from the authorization server.

For detailed examples about the types of access tokens supported, with example for each type of access token, refer to OAuth: Client Authentication with the Platform's OAuth Provider.

Note: there is a corresponding operation that performs the same action using HTTP GET: GET /oauth/oauth20/token. For information on why you might choose one or the other, see OAuth Operations: GET or POST?

Authorization Roles/Permissions: Anyone can run this operation.

This topic includes the following sections:

HTTP Method




Sample Request

The examples below shows token requests in an LDAP scenario, with several different grant types.

Sample Request URL


Sample request headers

Note: In the sample request headers below, the Authorization header consist of the client’s Basic authentication header, as explained in HTTP Basic Authentication. This is one way of sending the authorization credentials. As an alternative, you can send this information in the POST body or, if you are using the GET operation, in the request parameters. For more information, see OAuth: Client Authentication with the Platform's OAuth Provider.

POST /oauth/oauth20/token HTTP/1.1
Host: http://{oauth-provider-hostname}
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
Accept: application/json

Sample request body: authorization_code grant type

In the sample request body shown below, the client ID and client secret are included. When the Authorization header is included with the request message, as shown above, you don't need to send the client ID and client secret in the parameters. Send them either in the header or in the parameters. The below is an example of sending these values in the POST request body if the Authorization header was not sent.


Sample request body: client_credentials grant type (2-legged)


Sample request body: Resource Owner Credentials grant type


Request Headers

For general information on request header values, refer to HTTP Request Headers.

Header Description
Accept application/json
Content-Type application/x-www-form-urlencoded
Authorization Optional. The Authorization request header authenticates the client with the server.

Request Parameters

Note: the parameters below are all standard parameters defined in the OAuth 2.0, OpenID Connect, or JSON Web Token (JWT) specifications.

Parameter Parm Type Data Type Required Description
grant_type Form String Required

The OAuth grant type.

If the request is a request for a refresh token, the value must be set to refresh_token.

client_id Form String Optional

Unique identifier of the client application.

Must be sent; but can be sent as Authorization header.

client_secret Form String Optional

The client secret value; this value identifies the client with the provider.

Can be sent as Authorization header. Also, not needed for public client, even if Authorization header is not sent.

refresh_token Form String Optional Refresh Token grant type only: The refresh token.
scope Form String Optional

OAuth 2.0: standard scope parameter. One or more scopes configured in the OAuth provider. Space separator for multiple scopes.

The scope of the access request.

code Form String Optional Authorization Code grant type only: The authorization code that was previously received by the client application.
redirect_uri Form String Optional Authorization Code grant type only: The redirect URI of the client application, where it received the authorization code.
username Form String Optional Resource Owner Password Credentials only: The resource owner's username.
password Form String Optional Resource Owner Password Credentials only: The resource owner's password.
client_assertion_type Form String Optional

JWT Bearer Assertion grant type only:

The format of the assertion as identified by the Authorization Server. The value must be set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer.

client_assertion Form String Optional JWT Bearer Assertion grant type only: The assertion being used to authenticate the client. Only JWT compact serialization is allowed.
assertion Form String Optional JWT Bearer Assertion grant type only: The JWT Bearer Assertion.
code_verifier Form String Optional Used for PKCE support, when using Authorization Code grant type with PKCE. The code verifier is a string (40–128 characters) generated by the client. For more information on PKCE, see PKCE support with the Authorization Code grant type.


If successful, this operation returns HTTP status code 200, with the access token.

Sample Response

The sample response below shows successful completion of this operation.

Sample response headers: application/json

HTTP/1.1 200 OK
Content-Type: application/json
Sample response body: application/json

Sample response body #1

  "access_token": "SlAV32hkKG",
  "token_type": "Bearer",
  "refresh_token": "8xLOxBtZp8",
  "expires_in": 3600,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFlOWdkazcifQ.ewogImlzc

Sample response body: authorization_code grant type

  "access_token" : "d50d9fd00acf797ac409d5890fcc76669b727e63",
  "token_type" : "Bearer",
  "expires_in" : 1295998,
  "refresh_token" : "TZzj2yvtWlNP6BvG6UC5UKHXY2Ey6eEo80FSYax6Yv8"

Sample response body: Client Credentials grant type (2-legged)

  "access_token" : "4484e52dc4744374aced826a4543cd28948816ff",
  "token_type" : "Bearer",
  "expires_in" : 1295999

Sample response body: Resource Owner Credentials grant type

  "access_token" : "49fad390491a5b547d0f782309b6a5b33f7ac087",
  "token_type" : "Bearer",
  "expires_in" : 1295999,
  "refresh_token" : "USrAgmSf5MJ8N_RLQODa7rZ3zNs1Sj1GkSIsTsb4n-Y"

Sample response body: Error scenario

Note: in the example below, the state parameter is included in the error response. This would be the case in any scenario where it was included in the request.


Sample response: Authorization grant type with PKCE enabled, successful response

Valid in Version: 2020.2.0 and later

The example below shows a successful response from the token endpoint, when PKCE is enabled and the correct values were sent to the server in the request.


HTTP/1.1 200 OK
Date: Tue, 29 Dec 2020 18:55:47 GMT
Content-Type: application/json


  "access_token" : "bXadcrxDyYfoRmoadi66CmJYX6x8eIp2Yxmy2VK3",
  "token_type" : "Bearer",
  "expires_in" : 1295998,
  "refresh_token" : "dxUSdZtyn4lb4wHbTWYpSAEQp32j9IV7chu7Y-JFdTc"

Response Headers

For general information on response header values, refer to HTTP Response Headers.

Header Description
Content-Type application/json

Response Body: Success

Name Type Description
AccessTokenResponse AccessTokenResponse Contains information about the response to a request for an OAuth Access Token. Used by the token endpoint.

Response Body: Error Scenario

Name Type Description
AccessTokenErrorResponse AccessTokenErrorResponse Contains information about an error response returned by the OAuth Token Endpoint in response to a request for an OAuth 2.0 access token.

Error Codes/Messages

If the call is unsuccessful an error code/message is returned. One or more examples of possible errors for this operation are shown below.

Item Value
500 An error occurred processing the call.

More information about Akana OAuth API error messages.