Integration Reference
Next ReasonNext Reason CareersNext Identity Status

Token

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

Endpoint URL

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

PKCE (Proof Key for Code Exchange):

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={{code}}&redirect_uri={{redirect_uri}}}&code_verifier={{code_verifier}}'

Token with Basic Authorization:

curl -X POST \
'https://id.eu.nextreason.com/token' \
  -H 'Authorization: Basic {{REDACTED}}=' -d 'client_id={{client_id}}&grant_type=authorization_code&code={{code}}&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
`client_idThe ID used to authenticate the API call. This client ID is tied to your specific configurations and rules.
redirect_uriConfigures the URL the user is redirected after a successful authentication.

Important note: Ensure the URL is included in the list of allowed URLs for your integration. Contact your Next Reason consultant for assistance with adding URLs to the allowlist.
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).
`client_secretThe client_secret_post method is a way to authenticate OAuth 2.0 clients using a client secret when exchanging authorization codes or accessing protected resources. It involves sending the client_id and client_secret in the body of a POST request. This method is often used in secure server-to-server communications, especially where client credentials are sensitive.

Optional Parameters

The following parameters are optional.

ParameterDescription
code_verifierA high-entropy cryptographic random string created by the client at the beginning of the authorization process. It is used to prove possession of the code verifier during the token exchange.

Required only when using PKCE

The code verifier and code challenge work as a cryptographic pair to ensure that the authorization code exchange is secure.
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.

Response Handling

Your application will take this authorization code, and use it against the /token endpoint to get below response:doc:next-identity-journeys).

{ "token_type": "Bearer", "access_token": "ACCESS_TOKEN", "expires_in": 3600, "refresh_token": "REFRESH_TOKEN", "id_token": "ID_TOKEN" }

Configuration Options

The required authorization and parameters for this call will vary based on whether your application uses a public client ID (with PKCE) or a confidential client ID (which requires basic authorization with a client ID and secret).

Error Handling

CodeErrorCause
400 Bad Request{
"error": "invalid_grant",
"error_description": "invalid grant value"
}		Incorrect code
400 Bad Request{
"error": "invalid_request",
"error_description": "Could not find code/refresh_tokenparameter."
}		Missing code or refresh_token parameter
400 Bad Request{
"error": "invalid_request",
"error_description": "No authorization header"
}		Missing Authorization Header

(For Confidential Client)
400 Bad Request{
"error": "invalid_request",
"error_description": "Invalid authorization header"
} 		Invalid Authorization Header

(For Confidential Client)
400 Bad Request{
"error": "invalid_request",
"error_description": "Code verifier required"
} 		Missing Code Verifier in the call

(For Public Client)
400 Bad Request{
"error": "invalid_request",
"error_description": "authorization_code expired"
}		Expired Code (valid for a minute only)
400 Bad Request{
"error": "invalid_request",
"error_description": ""
}		Invalid redirect_uri
500 Internal Server Error{
"error": "internal_error"
} 		Incorrect basic authorization (if client is set to confidential)
403 Forbidden{
"error": "http_exception",
"error_details": {
"message": "Forbidden"
}
} 		Incorrect client_id

Security Considerations

To secure the authorization code flow in Oauth 2.0 and OIDC, consider the following mechanisms

PKCE (Proof Key for Code Exchange)

  • Primarily designed for public clients that cannot securely store client secrets (e.g., mobile apps, SPAs).
  • It uses a code_verifier and code_challenge to protect the authorization code exchange.

Confidential Client

  • Suitable for clients that can securely store client secrets (e.g., server-side applications).
  • This method relies on client credentials (client ID and secret) for authentication.

Integration

PKCE (Proof Key for Code Exchange)

Authorization Request

  1. The client generates a code_verifier (a high-entropy cryptographic random string).
  2. The client creates a code_challenge by hashing the code_verifier (using SHA-256) and then URL-encoding it.
  3. The client includes the code_challenge and code_challenge_method (typically "S256") in the authorization request.

Authorization Response

  • The authorization server returns an authorization code to the client.

Token Request

  • The client sends the authorization code and the code_verifier to the token endpoint.

Token Response

  • The authorization server validates the code_verifier against the code_challenge and, if valid, issues tokens to the client.

Confidential Client

Authorization Request

  • The client initiates the authorization request without needing to include a code_challenge since the client secret will be used later for authentication.

Authorization Response

  • The authorization server returns an authorization code to the client.

Token Request

  • The client sends the authorization code, client ID, and client secret to the token endpoint.

Token Response

  • The authorization server authenticates the client using the client secret and issues tokens if the credentials are valid.