Token
Exchange an authorization code for an access token
The code-for-token exchange will often be the second step in your integration with Next Identity Journeys.
In this step, the user has already been redirected back to your application after successful registration or sign in, and the redirect URL will contain an authorization code parameter.
Your application will take this authorization code, and use it against the /token endpoint to get an id_token (JWT with user data), access_token, and a refresh_token. You can also use the /token endpoint to refresh an access token by providing the refresh token and setting grant_type to refresh_token.
The lifetime of the id_token can be configured if needed (set to a shorter value) but is set to 14 days by default.
The needed authorization and parameters for this call will be different for your application depending on if your application is using a public client id type (and using PKCE) or is using a confidential client type (which will require basic authorization with client id and secret).
Integration
When configuring the token request there is a set of required parameters as described below. There are also additional parameters that can be part of the request depending on the business rules.
curl -X POST 'https://id.eu.nextreason.com/token'
-H "Content-Type: application/x-www-form-urlencoded" -d 'client_id={{CLIENT_ID}}&grant_type=authorization_code&code=a9enkuq4bksj2y&redirect_uri={{REDIRECT_URI}}&code_verifier={{CODE_VERIFIER}}'
curl -X POST \
'https://id.eu.nextreason.com/token' \
-H 'Authorization: Basic {{REDACTED}}=' -d 'client_id={{CLIENT_ID}}&grant_type=authorization_code&code=a9enkuq4bksj2y&redirect_uri={{REDIRECT_URI}}'
Base Domain
In the example above, the base URL is https://id.eu.nextreason.com/.
About base domains
Your base domain will be customized for your integration and for enterprise customers will be customized for your site name or brand name. If you don't know your base domain, please contact your Next Reason integration consultant.
Unless using PKCE protocol for this request, this call must be made in a secure server-to-server manner as it will contain a basic authorization header.
Endpoint
The endpoint used to exchange an authorization code for a token is /token. For refreshing an access token, use the same endpoint.
Parameters
Below are the required and optional parameters for the /token endpoint. Your specific parameters may vary depending on your configuration; if you're unclear on the parameters to use, please contact your Next Reason integration consultant.
Note that we are highlighting in bold the differences between Get Access Token and Refresh Token.
Required Parameters for Get Access Token
| Parameter | Description |
|---|---|
redirect_uri | Configures the URL the user is redirected to after successful authentication. Important note: This URL must be included in the safe list configuration. Contact your Next Reason integration consultant to add URLs to this list. |
client_id | The ID is used to authenticate the API call. This client ID is tied to your specific configurations and rules. Contact your Next Reason integration consultant if you do not know your client ID. |
grant_type | The value will be authorization_code if using an authorization code in this call. |
code | The authorization code received from an earlier step (such as a user sign-in or registration). |
Required Parameters for Refresh Token
| Parameter | Description |
|---|---|
redirect_uri | Configures the URL the user is redirected to after successful authentication. Important note: This URL must be included in the safe list configuration. Contact your Next Reason integration consultant to add URLs to this list. |
client_id | The ID used to authenticate the API call. This client ID is tied to your specific configurations and rules. Contact your Next Reason integration consultant if you do not know your client ID. |
grant_type | The value will be refresh_token for refreshing an access token. |
refresh_token | The refresh token received from an earlier /token call. |
Optional Parameters
The following parameters are optional.
| Parameter | Description |
|---|---|
code_verifier | Required only when using PKCE. The same code_verifier used for the initial token request must be used when refreshing the access token with PKCE. |
| Basic authorization header | Required in a confidential integration type (when not using PKCE). Note that the basic authorization must only be used when it can be passed in a secure server-to-server manner. |
Example Requests
curl -X POST 'https://id.eu.nextreason.com/token'
-H "Content-Type: application/x-www-form-urlencoded" -d 'client_id={{CLIENT_ID}}&grant_type=refresh_token&refresh_token={{REFRESH_TOKEN}}&redirect_uri={{REDIRECT_URI}}&code_verifier={{CODE_VERIFIER}}'
curl -X POST \
'https://id.eu.nextreason.com/token' \
-H 'Authorization: Basic {{REDACTED}}=' -d 'client_id={{CLIENT_ID}}&grant_type=refresh_token&refresh_token={{REFRESH_TOKEN}}&redirect_uri={{REDIRECT_URI}}'
Keep in mind that you need to replace {{REFRESH_TOKEN}} and other placeholders with actual values for your requests. The {{REFRESH_TOKEN}} value can be obtained from a previous /token request. If you are using PKCE, the {{CODE_VERIFIER}} value should be the same as in the original token request.
Updated about 1 year ago