How to integrate the Next Identity Hosted Journeys workflow to 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.

❗️

Differences in /token usage between Next Identity Hosted Journeys and Next Identity Journeys API

If your application is using Next Identity Journeys API for your integration, do not follow the instructions below; these are intended for Next Identity Hosted Journeys integrations.

Instead, refer to the Token integration reference for Next Identity Hosted 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

The authorization request consists of the base domain + the endpoint (/token) + parameters. Available parameters are listed below the example.

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

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.