/oauth/token

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_nativeoauth/register_nativeoauth/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.

Use this link for a video demo in Postman.

This endpoint includes the following methods:

  • GET


GET

Authentication

This endpoint supports both Basic authentication (recommended) and janrain-signed authentication.

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-dev.janraincapture.com

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 -G \
  -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
                                                            
      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 -G \
  -H "Authorization: Basic dXQ0YmdycmE3dzI4MmpjZm15cGZxeDlwemhxaGpqMmI6dW5qemU5bndrZnV5NmpwdzgzOHFwYTdhZDNoZG55YTY=" \
  --data-urlencode 'grant_type=refresh_token'\
  --data-urlencode 'refresh_token=m569crgh58ra33hy92e5'\
  https://my-app.janraincapture.com/oauth/token
                                                            
      Running this command in Postman

Authorized Clients

  • owner 
  • login_client 
  • direct_read_access 
  • direct_access 
  • access_issuer
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:
  • refresh_token
  • authorization_code
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.
 
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"
}