Credentials Exchange

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

Diagram showing the Actions Machine to Machine Flow and when the triggers inside of it run.

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.

Modify scopes on an access token

Use api.transaction.* methods to modify scopes in the Client Credentials Flow. Changes accumulate across Actions, and event.transaction.target_scopes immediately reflects the current set. After all Actions finish, Auth0 intersects it with the client grant. The following Action limits access to reading reports:

/**
 * @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.transaction.setTargetScopes(["read:reports"]);
};

Target-scope methods are the only way to modify scopes in this trigger. api.accessToken.addScope() and removeScope() are not available. To learn more, read Handling Scopes in Actions.

Brand Customization

Code Customization

Third-Party Customization

Credentials Exchange

References

Common use cases

Access control

Add custom claims to the access token

Modify scopes on an access token

​References

​Common use cases

​Access control

​Add custom claims to the access token

​Modify scopes on an access token

References

Common use cases

Access control

Add custom claims to the access token

Modify scopes on an access token