Exchange an authorization code

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.

API clientpPermissions

The following table indicates the API clients that can amd can't be used to call this operation:

Authentication

This operation supports both basic authentication (recommended) and janrain-signed authentication. For basic authentication, use the API client ID as your username and the API client secret as your password. See Get started for more information.

Base URL

The base URL for this operation is your Identity Cloud Capture domain; for example:

https://educationcenter.us- dev.janraincapture.com

Your Capture domains (also known as Registration domains) can be found in 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: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6dW5qemU5bndrZnV5NmpwdzgzOHFwYTdhZDNoZG55YTY=" \
  --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

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: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6dW5qemU5bndrZnV5NmpwdzgzOHFwYTdhZDNoZG55YTY=" \
  --data-urlencode 'grant_type=refresh_token'\
  --data-urlencode 'refresh_token=m569crgh58ra33hy92e5'\
  https://my-app.janraincapture.com/oauth/token

📘

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).

Parameters

All parameters need to be configured as x-www-form-urlencoded body parameters.

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"
}