> ## Documentation Index
> Fetch the complete documentation index at: https://docs-staging-actions-transaction-metadata.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

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

# Configure Custom Token Exchange

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

* [Complete the prerequisites](#prerequisites)
* [Enable Custom Token Exchange for your application](#enable-custom-token-exchange-for-your-application)
* [Configure](#configure-custom-token-exchange-profile) and [manage](#manage-custom-token-exchange-profile) 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](/docs/get-started/applications/first-party-and-third-party-applications)
* Is [OIDC-conformant](/docs/get-started/applications/application-settings#oauth)

## 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:

<Tabs>
  <Tab title="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**.
  </Tab>

  <Tab title="Management API">
    Use the Management API to make a `POST` call to [Create a Client](https://auth0.com/docs/api/management/v2/clients/post-clients) or a `PATCH` call to [Update a Client](https://auth0.com/docs/api/management/v2/clients/patch-clients-by-id), setting the `allow_any_profile_of_type` attribute under `token_exchange` to `["custom_authentication"]`:

    ```json lines theme={null}
    {
      "token_exchange": {
        "allow_any_profile_of_type": ["custom_authentication"]
      }
    }
    ```
  </Tab>
</Tabs>

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

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Custom DBs with import mode `ON` are only supported for `setUserById()` operations.
</Callout>

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](/docs/authenticate/custom-token-exchange/cte-example-use-cases).

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  `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`.
</Callout>

<Tabs>
  <Tab title="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](/docs/customize/actions/actions-templates). 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.

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      Once a profile is created, you cannot change which Action it's associated with.
    </Callout>
  </Tab>

  <Tab title="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](https://auth0.com/docs/api/management/v2/actions/post-action) and [deploy](https://auth0.com/docs/api/management/v2/actions/post-deploy-action) it.

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">Using the Auth0 CLI? If you haven't already, [set up and authenticate your CLI session](/docs/deploy-monitor/auth0-cli) before running these commands.</Callout>

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

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        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};"
          }'
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        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};"
        }'
        ```
      </Tab>
    </Tabs>

    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:

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api post "actions/actions/{yourActionId}/deploy"
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        curl --location --request POST 'https://{yourDomain}/api/v2/actions/actions/{yourActionId}/deploy' \
        --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
        ```
      </Tab>
    </Tabs>

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      An Action must be deployed before it can be bound to a Custom Token Exchange Profile.
    </Callout>

    To learn from example Custom Token Exchange Actions, read [Example Use Cases and Code Samples](/docs/authenticate/custom-token-exchange/cte-example-use-cases).

    ### 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:

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        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"
          }'
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        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"
        }'
        ```
      </Tab>
    </Tabs>

    | Parameter            | Description                                                                                                                                                                                                                                                                                                                         |
    | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `subject_token_type` | Unique profile token type URI starting with `https://` or `urn`<br /><br />The following namespaces are reserved and you can't use them:<br /><br /><ul><li>`http://auth0.com`</li><li>`https://auth0.com`</li><li>`http://okta.com`</li><li>`https://okta.com`</li><li>`urn:ietf`</li><li>`urn:auth0`</li><li>`urn:okta`</li></ul> |
    | `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:

    ```json lines theme={null}
    {
      "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"
    }
    ```
  </Tab>
</Tabs>

### Manage Custom Token Exchange Profile

<Tabs>
  <Tab title="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](#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**.

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      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.
    </Callout>
  </Tab>

  <Tab title="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.

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api get "token-exchange-profiles"
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        curl --location 'https://{yourDomain}/api/v2/token-exchange-profiles' \
        --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
        ```
      </Tab>
    </Tabs>

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

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      Once the Action is created, you cannot modify the Action ID.
    </Callout>

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api patch "token-exchange-profiles/{yourProfileId}" \
          --data '{
              "name": "external-idp-migration",
              "subject_token_type": "urn:partner0:external-idp-migration"
          }'
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        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"
        }'
        ```
      </Tab>
    </Tabs>

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

    <Tabs>
      <Tab title="Auth0 CLI">
        ```bash theme={null}
        auth0 api delete "token-exchange-profiles/{yourProfileId}" \
          --data ''
        ```
      </Tab>

      <Tab title="cURL">
        ```bash lines theme={null}
        curl --location --request DELETE 'https://{yourDomain}/api/v2/token-exchange-profiles/{yourProfileId}' \
        --header 'Authorization: Bearer <YOUR_MANAGEMENT_API_TOKEN>' \
        --data ''
        ```
      </Tab>
    </Tabs>

    <Callout icon="file-lines" color="#0EA5E9" iconType="regular">
      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.
    </Callout>
  </Tab>
</Tabs>