Token

Exchange an authorization code for an access token

Overview

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

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.

Required Parameters

The following parameters must be included on every /token request.

ParameterDescription
redirect_uriConfigures the URL the user is redirected after a 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_idThe 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_typeThe value will be "authorization_code" if using an authorization code in this call.
codeThe authorization code received from an earlier step (such as a user sign in or registration).

Optional Parameters

The following parameters are optional.

ParameterDescription
code_verifierRequired only when using PKCE
Basic authorization headerRequired 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.