Endpoint URL: {registrationDomain} /oauth/token
Description
Returns an access_token for an authenticated user. You will need to exchange either an authorization code or a refresh token in order to get a new access_token. An authorization_code may be generated when a user is authenticated through the JavaScript SDK or by using the oauth/auth_native, oauth/register_native, oauth/auth_native_traditional, or oauth/register_native_traditional endpoints. Authorization codes can also be obtained through the /access/getAuthorizationCode endpoint.
A refresh token is returned in the response each time this call is made and may be used for subsequent calls to obtain a new access token.
By default, an access token is valid for one hour, so you can use this API or the /access/getAccessToken endpoint to request a new one in order to keep a user authenticated through the Identity Cloud for the length of your site or application's session.
Respects the API Client Allow List:
Yes
API Client Permissions
The following table indicates the API clients that can (and the API clients that can't) be used to call this endpoint:
owner | access_issuer | direct_access | direct_read_access | login_client |
Yes | Yes | Yes | No | No |
Authentication
This endpoint supports both Basic authentication (recommended) and janrain-signed authentication. Note that:
- If you retrieve an authorization code by using the /auth_native_traditional endpoint you must use the client ID and client secret of the API client assigned to /auth_native_traditional's client_id parameter.
- If you retrieve an authorization code by using the /getAuthorizationCode endpoint you must use the client ID and client secret of the API client assigned to /getAuthorizationCode's for_client_id parameter (assuming that your API cal included for_client_id).
In other words, suppose you use /getAuthorizationCode and set the for_client_id parameter to 3bchk5hsx6v58dkn288nbybmxfyk32u7. In that case, when configuring Basic authentication for /oauth/token, you must use 3bchk5hsx6v58dkn288nbybmxfyk32u7 as the username and 3bchk5hsx6v58dkn288nbybmxfyk32u7's client secret as the password.
If you don't include for_client_id when retrieving an authorization code then you can use any login client to exchange that code for an access token. As a general rule, it's recommended that you use for_client_id when calling the /getAuthorizationCode endpoint (the client_id parameter is required when using /auth_native_traditional). That way, the same login client that retrieves the authorization code is used to exchange that code.
How to Create an Authentication String
Base URL
The base URL for this endpoint is your Identity Cloud Capture domain; for example:
https://educationcenter.us-
Your Capture domains (also known as Registration domains) can be found in the Console on the Manage Application page:
Examples
Example 1: Exchange Authorization Code for Access Token
This command exchanges the authorization code dwtztmqaehzeee for an access token and a refresh token.
curl -X POST \ -H "Authorization: BasicdXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6dW5qemU5bndrZnV5NmpwdzgzOHFwYTdhZDNoZG55YTY=" \ --data-urlencode 'grant_type=authorization_code'\ --data-urlencode 'code=dwtztmqaehzeee'\ --data-urlencode 'redirect_uri=http://documentation.janraincapture.com/oauth'\ https://my-app.janraincapture.com/oauth/token
Running this command in Postman
Example 2: Exchange Refresh Secret for Access Token
This command exchanges the refresh token m569crgh58ra33hy92e5 for a new access token.
curl -X POST \ -H "Authorization: BasicdXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6dW5qemU5bndrZnV5NmpwdzgzOHFwYTdhZDNoZG55YTY=" \ --data-urlencode 'grant_type=refresh_token'\ --data-urlencode 'refresh_token=m569crgh58ra33hy92e5'\ https://my-app.janraincapture.com/oauth/token
Running this command in Postman
Note. While any client can exchange an authorization_code for an access_token, that code must have been provisioned for that client (e.g., specifying a value in for_client_id when generating a code via oauth/getAuthorizationCode)
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| grant_type | string | Yes | Type of access grant you are passing into the call. If set to refresh_token, then you must supply the refresh_token parameter. If set to authorization_code, then you must supply the code parameter. Allowed values are:
|
| code | string | Yes | Authorization code received after a user has successfully authenticated or after you have made a call to the /access/getAuthorizationCode API. This parameter is required only when the grant_type is set to authorization_code. |
| redirect_uri | string | Yes | The redirect_uri that was passed into a previous API call to obtain an authorization_code, or the redirectUri setting configured in a widget-based implementation. Required only when the grant_type is set to authorization_code. Important. The redirect_uri parameter must be set to the same value specified for the redirect_uri in the API cal that returned the authorization code. This is true regardless of whether you obtained your authorization code from the /access/getAuthorizationCode endpoint or from the /auth_native_traditional endpoint. |
| refresh_token | string | Refresh token received from a previous oauth/token call. A new pair of access and refresh tokens will be returned. This parameter is required only when the grant_type is set to refresh_token. |
Responses
200 OK
Successful Response
A successful response will include a new pair of access and refresh tokens along with the access_token expiration time in seconds.
{
"access_token": "8r8v9ad6dajnbk5t",
"expires_in": 3600,
"refresh_token": "f4mrz7dzatqm272tpey2",
"stat": "ok"
}
Error - Invalid Authorization Code
The example error response below indicates that the authorization_code included in the call is not valid. This may be encountered when the code has expired, has already been used, or when the client ID that was used to generate the code does not match the client ID used to make the oauth/token call.
{
"request_id": "8sphe693btp8hgv4",
"code": 413,
"error_description": "authorization_code is not valid",
"sub_error": "no_access_grant",
"error": "invalid_request",
"stat": "error"
}
Error - Invalid Redirect URI
The example error response below indicates that the redirect_uri included in the oauth/token call does not match the value that was used when generating the code passed into the authorization_code parameter.
{
"received_value": "http://localhost",
"request_id": "hbpbfre9qnsbpjbv",
"code": 420,
"expected_value": "http://localhost2",
"error_description": "redirect_uri does not match expected value",
"sub_error": "redirect_uri_mismatch",
"error": "invalid_request",
"stat": "error"
}
Error - Invalid Refresh Token
The example error response below indicates that the refresh_token included in the call is not valid. This may be encountered when the token has expired or has already been used.
{
"request_id": "rgg3nzte9kakua38",
"code": 200,
"error_description": "unknown refresh_token",
"sub_error": "invalid_argument",
"error": "invalid_request",
"stat": "error"
}
Error - Invalid API Client Permissions
The example error response below indicates that API client credentials used to authenticate the call are not valid for the Registration application.
{
"request_id": "mzzufjfz8hvyzemd",
"code": 402,
"error_description": "credentials are not valid",
"sub_error": "invalid_client_credentials",
"error": "invalid_client",
"stat": "error"
}