Configure Custom Token Exchange

Learn how to configure the Custom Token Exchange by associating an Action with a Custom Token Profile.

To configure the Custom Token Exchange for your application, you need to:

• Complete the prerequisites
• Enable Custom Token Exchange for your application
• Configure and manage a Custom Token Exchange Profile

Prerequisites

Before configuring the Custom Token Exchange, make sure your application meets the following prerequisites:

• Is a first-party client
• Is OIDC-conformant

Enable Custom Token Exchange for your application

Custom Token Exchange can be enabled across multiple applications. By default Custom Token Exchange is disabled for an application, to enable it:

Auth0 Dashboard

1. Navigate to Applications > Applications and select your application.
2. Select the Settings tab.
3. Find Custom Token Exchange and toggle it on.
4. Select Save.

Management API

Use the Management API to make a POST call to Create a Client or a PATCH call to Update a Client, setting the allow_any_profile_of_type attribute under token_exchange to ["custom_authentication"]:

{
  "token_exchange": {
    "allow_any_profile_of_type": ["custom_authentication"]
  }
}

Once Custom Token Exchange is enabled for the application, also enable the connection you want to use with Custom Token Exchange for the application.

Custom DBs with import mode ON are only supported for setUserById() operations.

Note the application’s client_id and client_secret for later use when calling the /oauth/token endpoint.

Configure Custom Token Exchange Profile

Each Custom Token Exchange Profile establishes a one-to-one mapping between a subject_token_type and an Action, which contains the code logic for a specific use case.

Custom Token Exchange requests sent to the /oauth/token endpoint with a specific subject_token_type value will map to the corresponding Custom Token Profile and route to the associated Action for processing.

Use the Custom Token Exchange Event and API objects to write the Action associated with a profile. The Action should:

• Decode and validate the subject_token based on the subject_token_type. This will provide you with information about the user for the transaction.
• Enforce any authorization policy you may need to apply for the transaction.

Once you are sure the transaction can proceed, set the user. Auth0 will then issue access, ID, and refresh tokens for this user as a form of user authentication.

To learn from example Custom Token Exchange Actions, read Example Use Cases and Code Samples.

subject_token_type must be a unique URI starting with https:// or urn. The following namespaces are reserved and you can’t use them: http://auth0.com, https://auth0.com, http://okta.com, https://okta.com, urn:ietf, urn:auth0, urn:okta.

Auth0 Dashboard

1. Navigate to Authentication > Custom Token Exchange and select Create Profile.
2. In the Create Profile dialog:
   • Enter a Name for the profile.
   • Enter a unique Subject Token Type.
   • Choose how to provide the Action associated with this profile:
     • Start from scratch: enter a Name for the new Action. Auth0 creates an empty Action, bound to the Custom Token Exchange trigger, once you create the profile.
     • Create from Template: select an Action Template. Auth0 creates a new Action prefilled with the template’s code.
     • Use existing: select an existing Action already bound to the Custom Token Exchange trigger.
3. Select Create. Auth0 creates the profile — and the Action, if you chose to create a new one or one from a template — and takes you to the profile’s Details page.
4. On the Details page:
   • Edit the profile’s Name or Subject Token Type as needed.
   • Edit the associated Action’s Name as needed.
   • Use the inline code editor to edit the associated Action’s code. Select Save to save a draft, or Deploy to deploy a new version of the Action.

Once a profile is created, you cannot change which Action it’s associated with.

Management API

Creating a Custom Token Exchange Profile via the Management API is a two-step process: first create the Action, then create the profile referencing that Action’s ID.

Create the Action

Write your Action’s code, then use the Management API to create and deploy it.

Using the Auth0 CLI? If you haven’t already, set up and authenticate your CLI session before running these commands.

1. Make the following POST request to the /actions/actions endpoint to create the Action, bound to the custom-token-exchange trigger:

Auth0 CLI

auth0 api post "actions/actions" \
  --data '{
      "name": "<YOUR_ACTION_NAME>",
      "supported_triggers": [
        { "id": "custom-token-exchange", "version": "v1" }
      ],
      "code": "exports.onExecuteCustomTokenExchange = async (event, api) => {\n  // your custom logic here\n};"
  }'

cURL

curl --location 'https://{yourDomain}/api/v2/actions/actions' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data '{
    "name": "<YOUR_ACTION_NAME>",
    "supported_triggers": [
        { "id": "custom-token-exchange", "version": "v1" }
    ],
    "code": "exports.onExecuteCustomTokenExchange = async (event, api) => {\n  // your custom logic here\n};"
}'

You should receive the Action ID in the response body’s id property. You need it both to deploy the Action and to create the Custom Token Exchange Profile.

2. Make the following POST request to the /actions/actions/{id}/deploy endpoint to deploy the Action:

Auth0 CLI

auth0 api post "actions/actions/{yourActionId}/deploy"

cURL

curl --location --request POST 'https://{yourDomain}/api/v2/actions/actions/{yourActionId}/deploy' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \

An Action must be deployed before it can be bound to a Custom Token Exchange Profile.

To learn from example Custom Token Exchange Actions, read Example Use Cases and Code Samples.

Create the Custom Token Exchange Profile

To create the Custom Token Exchange Profile, use the Management API to make a POST request with the following parameters to the /token-exchange-profiles endpoint:

Auth0 CLI

auth0 api post "token-exchange-profiles" \
  --data '{
      "name": "<YOUR_PROFILE_NAME>",
      "subject_token_type": "<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
      "action_id": "<YOUR_ACTION_ID>",
      "type": "custom_authentication"
  }'

cURL

curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data '{
    "name": "<YOUR_PROFILE_NAME>",
    "subject_token_type": "<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
    "action_id": "<YOUR_ACTION_ID>",
    "type": "custom_authentication"
}'

Parameter	Description
subject_token_type	Unique profile token type URI starting with https:// or urn The following namespaces are reserved and you can’t use them: http://auth0.com https://auth0.com http://okta.com https://okta.com urn:ietf urn:auth0 urn:okta
action_id	Action ID of Action associated with the Custom Token Profile.
type	Should be set to custom_authentication.

If you’ve successfully created a Custom Token Exchange Profile, you should receive a response like the following:

{
  "id":"tep_9xqewuejpa2RTltf",
  "name":"<YOUR_PROFILE_NAME>",
  "type":"custom_authentication",
  "subject_token_type":"<YOUR_UNIQUE_PROFILE_TOKEN_TYPE_URI>",
  "action_id":"<YOUR_ACTION_ID>",
  "created_at":"2025-01-30T13:19:00.616Z",
  "updated_at":"2025-01-30T13:19:00.616Z"
}

Manage Custom Token Exchange Profile

Auth0 Dashboard

1. Navigate to Authentication > Custom Token Exchange to see the list of your Custom Token Exchange Profiles, showing each profile’s Name, Subject Token Type, and Action ID.
2. Select a profile to open its Details page, where you can edit its Name, Subject Token Type, and the associated Action’s Name and code (see Configure Custom Token Exchange Profile above).
3. To delete a profile, select the options menu (the three-dot icon) next to it in the list, then select Delete.

An Action bound to a Custom Token Exchange Profile cannot be deleted on its own. Delete the profile first, then delete the Action if you no longer need it.

Management API

To manage your Custom Token Exchange Profile, use the Management API to make requests to the /token-exchange-profiles endpoint.

To get all your Custom Token Exchange Profiles, make the following GET request to the /token-exchange-profiles endpoint. The /token-exchange-profiles endpoint supports checkpoint pagination if you have several profiles.

Auth0 CLI

auth0 api get "token-exchange-profiles"

cURL

curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \

To update the name or the subject_token_type of an existing profile, make the following PATCH request to the /token-exchange-profiles endpoint.

Once the Action is created, you cannot modify the Action ID.

Auth0 CLI

auth0 api patch "token-exchange-profiles/{yourProfileId}" \
  --data '{
      "name": "external-idp-migration",
      "subject_token_type": "urn:partner0:external-idp-migration"
  }'

cURL

curl --location --request PATCH 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data '{
    "name": "external-idp-migration",
    "subject_token_type": "urn:partner0:external-idp-migration"
}'

To delete a Custom Token Exchange Profile, make the following DELETE request to the /token-exchange-profiles endpoint:

Auth0 CLI

auth0 api delete "token-exchange-profiles/{yourProfileId}" \
  --data ''

cURL

curl --location --request DELETE 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
--header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
--data ''

An Action bound to a Custom Token Exchange Profile cannot be deleted on its own. Delete the profile first, then delete the Action if you no longer need it.