Get Token

Custom Token Exchange (CTE) provides a mechanism for applications to exchange pre-existing identity tokens for Auth0 tokens by invoking the /oauth/token…

POST /oauth/token

Custom Token Exchange (CTE) provides a mechanism for applications to exchange pre-existing identity tokens for Auth0 tokens by invoking the /oauth/token endpoint, adhering to the specifications of RFC 8693. This functionality is instrumental in addressing advanced integration requirements, such as exchanging existing Auth0 tokens to access another audience on behalf of the same user, facilitating the integration of external identity providers, or enabling seamless user migration into the Auth0 platform. The exchange process is fully governable, as developers can control its details using their custom logic running in a dedicated Auth0 Action for the associated use case.

Custom Token Exchange is currently available in Early Access. By using this feature, you agree to the applicable Free Trial terms in Okta’s Master Subscription Agreement. It is your responsibility to securely validate the user’s subject_token. See the User Guide for more details.

Remarks

• The scopes issued to the application may differ from the scopes requested. In this case, a scope parameter will be included in the response JSON. Scopes are filtered out as explained in API Access Policies for Applications

• The subject_token_type must correspond to an existing Custom Token Exchange Profile and an associated Action.

• For non-confidential applications that cannot keep the Client Secret safe (for example, native apps), the endpoint supports passing no Client Secret but the application itself must have the property tokenEndpointAuthMethod set to none. You can do this either from the UI (Dashboard > Applications > Application Settings) or using the Management API.

• You have to Enable Custom Token Exchange for your application. To learn more, read the Custom Token Exchange documentation.

• actor_token and actor_token_type must both be present or both absent. Providing only one returns a 400 error with code invalid_request.

• When actor_token is present, refresh tokens are not issued. The offline_access scope is excluded from the response.

• MFA is not compatible with transactions where an actor is set via setActor(). If MFA is required and the Custom Token Exchange Action sets an actor, the request returns a 400 error: MFA is not supported using actor_token with the requested token exchange profile.

• When the Action calls setActor(), issued access tokens and ID tokens include an act claim representing the delegation chain. The act claim is also included in the userinfo response.

Parameters

DPoP · string

A DPoP proof for the request. This is optional and only required if your application uses Demonstrating Proof-of-Possession.

auth0-forwarded-for · string

End-user IP as a string value. Set this if you want Suspicious IP Throttling protection to work in server-side scenarios.

Request Body

grant_type · string · required

Denotes the flow you are using. For Custom Token Exchange, use urn:ietf:params:oauth:grant-type:token-exchange.

Allowed values: urn:ietf:params:oauth:grant-type:token-exchange

subject_token_type · string · required

The type of the subject token. For Custom Token Exchange, this can be any URI scoped under your own ownership, such as http://acme.com/legacy-token or urn:acme:legacy-token. The following namespaces are reserved and cannot be used: http://auth0.com, https://auth0.com, http://okta.com, https://okta.com, urn:ietf, urn:auth0, urn:okta.

subject_token · string · required

The subject token, which your action should validate and use to identify the user.

client_id · string · required

Your application’s Client ID. As for other grant types, you can also pass the client ID in the Authorization header using HTTP Basic Auth.

client_secret · string

(Optional) Your application’s Client Secret. As for other grant types, you can also pass the client secret in the Authorization header using HTTP Basic Auth. Other alternatives are also available as explained in Auth0 Authentication API reference docs. Because Custom Token Exchange can be used by public applications, read Attack Protection to implement additional security.

audience · string

(Optional) The unique identifier of the target API you want to access. The default tenant audience will be used when not present, as configured in Tenant Settings.

resource · string

(Optional) The identifier of the target API (resource server) you want to access. Must match an API Identifier registered in your Auth0 tenant. Used as an alternative to audience when the tenant’s Resource Parameter Compatibility Profile is set to compatibility.

scope · string

(Optional) The OAuth2 scope parameter.

organization · string

(Optional) The organization or identifier with which you want the request to be associated. Alternatively, you can specify an organization name if Use Organization Names in Authentication API is specified.

actor_token · string

(Optional) A token identifying the actor performing delegation on behalf of the subject user. Must be provided together with actor_token_type. When present, refresh tokens will not be issued.

actor_token_type · string

(Optional) The type of the actor token. Must be provided together with actor_token. For Auth0 ID tokens, use urn:ietf:params:oauth:token-type:id_token for automatic server-side validation (signature, expiry, issuer, user lookup). For other values, follow the same namespace restrictions as subject_token_type.

Response

Status	Description
200	Successful response