Credentials Exchange - Auth0 Docs

The credentials-exchange trigger runs when an is being issued via the Client Credentials Flow, before the access token is returned.

Actions in this flow are blocking (synchronous): they execute as part of the trigger’s process and prevent the rest of the Auth0 pipeline from running until the Action completes.

References

Event object: Provides contextual information about the request for a client credentials exchange.
API object: Provides methods for changing the behavior of the flow.

Common use cases

Access control

A credentials-exchange Action can be used to deny an access token based on custom logic:

/**
 * @param {Event} event - Details about client credentials grant request.
 * @param {CredentialsExchangeAPI} api - Interface whose methods can be used to change the behavior of client credentials grant.
 */
exports.onExecuteCredentialsExchange = async (event, api) => {
  if (event.request.geoip.continentCode === "NA") {
    api.access.deny('invalid_request', "Access from North America is not allowed.");
  }
};

Add custom claims to the access token

A credentials-exchange Action can be used to add custom claims to an access token:

/**
 * @param {Event} event - Details about client credentials grant request.
 * @param {CredentialsExchangeAPI} api - Interface whose methods can be used to change the behavior of client credentials grant.
 */
exports.onExecuteCredentialsExchange = async (event, api) => {
  api.accessToken.setCustomClaim("https://my-api.exampleco.com/request-ip", event.request.ip);
};

We strongly recommend using a namespaced custom claim in the form of a URI. To learn more about namespaced and non-namespaced custom claims, read Create Custom Claims.