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 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 |
|---|---|---|---|---|
| ✓ | ✓ | ✓ | ✗ | ✗ |
Authentication
This endpoint 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.
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 -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
| Parameter | Tyoe | 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 passed into a previous API call to obtain an authorization_code, or the redirectUri setting configured in a JavaScript SDK-based implementation. Required only when the grant_type is set to authorization_code. |
| refresh_token | string | Yes | 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"
}