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
URL
Sample Request
Request Headers
Request Parameters

Response
Sample Response
Response Headers
Response Body
Error Codes/Messages

HTTP Method

POST

URL

https://{oauth-provider-url}/oauth/oauth20/token

Sample Request

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

Sample Request URL

https://{oauth-provider-url}/oauth/oauth20/token

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.

client_id=acmepaymentscorp-3rCEQzwEHMT9PPvuXcClpe3v&client_secret=e5868ebb4445fc2ad9f949956c1cb9ddefa0d421&code=T8Y2h7zvp-tviqe2gQQ_VGQKMizn8jRgxZ74hA&redirect_uri=http%3A%2F%2Facmepaymentscorp.com%3A9900%2Fui%2Fapps%2Facmepaymentscorp%2F_VWQJeFH76RyfD6M6FRO5Svg%2Fresources%2Fconsole%2Fglobal%2Foauthclientredirect.html%3Fdynamic%3Dtrue&grant_type=authorization_code&scope=Scope1

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

client_id=acmepaymentscorp-3rCEQzwEHMT9PPvuXcClpe3v&client_secret=e5868ebb4445fc2ad9f949956c1cb9ddefa0d421&grant_type=client_credentials&scope=Scope1

Sample request body: Resource Owner Credentials grant type

client_id=atmosphere-3rCEQzwEHMT9PPvuXcClpe3v&client_secret=e5868ebb4445fc2ad9f949956c1cb9ddefa0d421&grant_type=password&scope=Scope1&username=eng100&password=password

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.

Response

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
    yI6ICJodHRwOi8vc2VydmVyLmV4YW1wbGUuY29tIiwKICJzdWIiOiAiMjQ4Mjg5
    NzYxMDAxIiwKICJhdWQiOiAiczZCaGRSa3F0MyIsCiAibm9uY2UiOiAibi0wUzZ
    fV3pBMk1qIiwKICJleHAiOiAxMzExMjgxOTcwLAogImlhdCI6IDEzMTEyODA5Nz
    AKfQ.ggW8hZ1EuVLuxNuuIJKX_V8a_OMXzR0EHR9R6jgdqrOOF4daGU96Sr_P6q
    Jp6IcmD3HP99Obi1PRs-cwh3LO-p146waJ8IhehcwL7F09JdijmBqkvPeB2T9CJ
    NqeGpe-gccMg4vfKjkM8FcGvnzZUN4_KSP0aAp1tOJ1zZwgjxqGByKHiOtX7Tpd
    QyHE5lcMiKPXfEIQILVq0pc_E2DzL7emopWoaoZTF_m0_N0YzFC6g6EJbOEoRoS
    K5hoDalrcvRYLSrQAZZKflyuVCyixEoV9GfNQC3_osjzw2PAithfubEEBLuVVk4
    XUVrWOLrLl0nx7RkKU8NXNHq-rvKMzqg"
}

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.

{
  error=invalid_request,
  error_description=Unsupported%20response_type%20value,
  state=af0ifjsldkj
}

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.

Headers:

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

Body:

{
  "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.