/oauth/token

This endpoint can be used to obtain a Registration 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 Janrain widget or through the oauth/auth_nativeoauth/register_nativeoauth/auth_native_traditional, or oauth/register_native_traditional endpoints if your response type has been set to code. Authorization codes may 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. A refresh_token is valid for one use only, so a new one must be used for each subsequent call.

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 Janrain 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

Base URL

The base URL for this endpoint is your Janrain Capture domain; for example:

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

Your Capture domains (also known as Registration domains) can be found in the Janrain Console on the Manage Application page:

Examples

Example 1: Exchange Authorization Code for Access Token


curl -H "Authorization: Basic aW1fYV...NfbXk=" \
  --data-urlencode 'grant_type=authorization_code'\
  --data-urlencode 'code=7n12d0snfps1bb'\
  --data-urlencode 'redirect_uri=http://example.com'\
  https://my-app.janraincapture.com/oauth/token
                                                            

Example 2: Exchange Refresh Secret for Access Token


curl -H "Authorization: Basic aW1fYV...NfbXk=" \
  --data-urlencode 'grant_type=refresh_token'\
  --data-urlencode 'refresh_token=bjkxc67m3nkva2bd982z'\
  https://my-app.janraincapture.com/oauth/token
                                                            

Running Code Samples Using Postman

The Janrain REST API code samples are written using Curl, but they can easily be run from within Postman. To use one of our code samples in Postman:

  1. Click the Copy to Clipboard button located directly beneath the code sample
  2. In Postman, click Import to display the Import dialog box.
  3. In the Import dialog box, click Paste Raw Text, and then paste in the copied code. The Import dialog box should look similar to this:

  4. Click Import, and the Curl command will be converted to a format that can be run from within Postman. All you need to do now is configure the command to work with your Janrain implementation.

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)

Security

  •  janrain-signed
  •  basic-auth

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.


{
  "access_token": "8r8v9ad6dajnbk5t",
  "expires_in": 3600,
  "refresh_token": "f4mrz7dzatqm272tpey2",
  "stat": "ok"
}
                                                            

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