> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Token Exchange

> Custom Token Exchange enables applications to exchange their existing tokens for Auth0 tokens.

export const ReleaseStageNotice = ({feature, stage, plans, contact, terms}) => {
  const stageTextMap = {
    "beta": "Beta",
    "ea": "Early Access"
  };
  const stageText = stageTextMap[stage] || "a product release stage";
  const prsLink = "/docs/troubleshoot/product-lifecycle/product-release-stages";
  const linkify = (text, url) => {
    return <a href={url} target="_blank" rel="noreferrer" class="link">{text}</a>;
  };
  const includeDetails = (plans, contact, terms) => {
    const hasDetails = terms || plans || contact;
    if (!hasDetails) return null;
    return <span data-as="p">
            {plans && <>This feature is available for {linkify(`${plans} plans`, "https://auth0.com/pricing")}. </>}
            {contact && "To participate, contact " + contact + ". "}
            {terms && <>By using this feature, you agree to the applicable Free Trial terms in Okta's {linkify("Master Subscription Agreement", "https://www.okta.com/legal")}.</>}
        </span>;
  };
  return <Warning>
            <span data-as="p">
                <strong>The {feature} feature is in {linkify(stageText, prsLink)}.</strong>
            </span>

            {includeDetails(plans, contact, terms)}
        </Warning>;
};

<ReleaseStageNotice feature="Custom Token Exchange (CTE)" stage="ea" plans="B2C Professional, B2B Professional, and Enterprise" terms="true" />

Custom Token Exchange enables applications to exchange their existing tokens for Auth0 tokens when calling the `/oauth/token` endpoint, as defined in [RFC 8693](https://datatracker.ietf.org/doc/html/rfc8693). Common use cases for the Custom Token Exchange include:

* Getting Auth0 tokens for another <Tooltip tip="Audience: Unique identifier of the audience for an issued token. Named aud in a token, its value contains the ID of either an application (Client ID) for an ID Token or an API (API Identifier) for an Access Token." cta="View Glossary" href="/docs/glossary?term=audience">audience</Tooltip>
* Integrating with an external <Tooltip tip="Identity Provider (IdP): Service that stores and manages digital identities." cta="View Glossary" href="/docs/glossary?term=identity+provider">identity provider</Tooltip>
* Migrating to Auth0
* Delegated authorization: A principal (such as a service, AI agent, or support agent) acts on behalf of a user

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

Each Custom Token Exchange request maps to a [Custom Token Exchange Profile](/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile) that is governed by an [Action](/docs/customize/actions), where you can:

* Write custom code to decode and validate `subject_tokens` passed to the `/oauth/token` endpoint
* Authorize access and set the user to proceed with the transaction.

You can [configure multiple Custom Token Exchange Profiles](/docs/authenticate/custom-token-exchange/configure-custom-token-exchange#create-custom-token-exchange-profile) for an application. After the Auth0 Authorization Server validates that the Custom Token Exchange request is valid and maps to an existing Custom Token Exchange Profile, the [Custom Token Exchange trigger](/docs/customize/actions/explore-triggers/signup-and-login-triggers/custom-token-exchange-trigger) executes the single Action associated with that profile. The application can then leverage the Custom Token Exchange to authenticate and get Auth0 access, ID, and refresh tokens for the user.

<Callout icon="file-lines" color="#0EA5E9" iconType="regular">
  Custom Token Exchange gives you the added flexibility to set the user for the transaction by taking on the additional responsibility of securely validating the corresponding subject token that identifies the user for the transaction.

  Remember that subject and actor tokens used with Custom Token Exchange can be any token format or type you require, as long as your Action code can interpret them. **You must implement strong validation of the tokens you receive and accept.** If you fail to do so, you open yourself up to different attack vectors, such as spoofing or replay attacks, resulting in bad actors being able to authenticate with someone else’s user ID or acting on their behalf in an unauthorized manner.

  To learn about different options for implementing secure validation of your subject tokens, read and apply the recommendations included in [Example Use Cases and Code Samples](/docs/authenticate/custom-token-exchange/cte-example-use-cases). Make sure you also take into consideration and apply [Attack Protection](/docs/authenticate/custom-token-exchange/cte-attack-protection) capabilities.
</Callout>

## Tenant logs

Each Custom Token Exchange transaction generates a tenant event log:

* Successful transactions: `secte` logs
* Failed transactions: `fecte` logs

When an actor is set via `setActor()`, the `actor` property (containing `sub` and any nested `actor`) is included in `secte` log entries for audit purposes.

Use the tenant logs to help you troubleshoot any issues you encounter with your token exchange.

## Limitations

Custom Token Exchange does not support the following:

* MFA API methods `api.authentication.challengeWith()` and `api.authentication.EnrollWith()`
* Custom DB Connections with import mode `ON` are not supported for `setUserByConnection()` operations
* Third-party and non-OIDC conformant clients
* The target API must have **Allow Skipping User Consent** enabled since consent cannot be collected in a non-interactive flow.