Skip to main content
The End of Life (EOL) date of Rules and Hooks will be November 18, 2026, and they are no longer available to new tenants created as of October 16, 2023. Existing tenants with active Hooks will retain Hooks product access through end of life.We highly recommend that you use Actions to extend Auth0. With Actions, you have access to rich type information, inline documentation, and public npm packages, and can connect external integrations that enhance your overall extensibility experience. To learn more about what Actions offer, read Understand How Auth0 Actions Work.To help with your migration, we offer guides that will help you migrate from Rules to Actions and migrate from Hooks to Actions. We also have a dedicated Move to Actions page that highlights feature comparisons, an Actions demo, and other resources to help you on your migration journey.To read more about the Rules and Hooks deprecation, read our blog post: Preparing for Rules and Hooks End of Life.
Because we plan to remove Rules and Hooks functions in 2026, you should create new Rules or Hooks only in your Development environment and only to test migration to Actions.To learn how to migrate your Rules to Actions, read Migrate from Rules to Actions. To learn how to migrate your Hooks to Actions, read Migrate from Hooks to Actions.
You can change scopes and add custom claims in the tokens issued through the Client Credentials Flow by adding Hooks. Hooks allow you to customize the behavior of Auth0 using Node.js code. They are secure, self-contained functions associated with specific extensibility points of the Auth0 platform (like the Client Credentials flow). Auth0 invokes the Hooks at runtime to execute your custom logic. You can manage Hooks using the or the .
Although you may create multiple hooks for any given extensibility point, each extensibility point may have only one enabled hook at a time. Any subsequent hooks you create for that extensibility point are automatically disabled, so you must explicitly enable them. The enabled hook will be executed for all applications and APIs.

​
Prerequisites

Before beginning this tutorial, you must:

​
Steps

  1. Create Hook: Create a hook that will customize your token.
  2. Test Hook: Test your new hook by running a Client Credentials Flow and decoding the access token.

​
Create a Hook

In this example, you will:
  • add an arbitrary claim (https://foo.com/claim) to the Access Token
  • add an extra permission to your configured API
Create a Hook to customize your token. When asked to choose an extensibility point, select Client Credentials Exchange, and add the following code in the editor: 
module.exports = function(client, scope, audience, context, cb) {
  var access_token = {};
  access_token['https://foo.com/claim'] = 'bar';
  access_token.scope = scope;
  access_token.scope.push('extra');
  cb(null, access_token);
};
Auth0 returns profile information in a structured claim format as defined by the OpenID Connect (OIDC) specification. This means that custom claims added to ID tokens or access tokens must conform to guidelines and restrictions to avoid possible collisions.

​
Test your Hook

To test the hook you just created you need to run a Client Credentials exchange, get the , decode it, and review its contents.

​
Get token

To get a token, make a POST call to the Client Credentials Flow endpoint. Be sure to replace CLIENT_ID, CLIENT_SECRET, and API_IDENTIFIER placeholder values with your application’s , your application’s , and your API’s Identifier, respectively. You can find the Client ID and Client Secret in your Application settings and the API Identifier in your API settings. 
curl --request POST \
  --url 'https://{yourDomain}/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data 'client_id={yourClientId}' \
  --data client_secret=YOUR_CLIENT_SECRET \
  --data audience=YOUR_API_IDENTIFIER
A successful response will include:
  • an access_token,
  • its expiration time in seconds (expires_in),
  • the token’s type set as Bearer (token_type), and
  • an extra permission (scope) (which was added by your Hook)
HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ik5ESTFNa05DTVRGQlJrVTRORVF6UXpFMk1qZEVNVVEzT1VORk5ESTVSVU5GUXpnM1FrRTFNdyJ9.eyJpc3MiOiJodHRwczovL2RlbW8tYWNjb3VudC5hdXRoMC3jb20vIiwic3ViIjoic0FRSlFpQmYxREw0c2lqSVZCb2pFRUZvcmRoa0o4WUNAY2xpZW50cyIsImF1ZCI6ImRlbW8tYWNjb3VudC5hcGkiLCJleHAiOjE0ODc3NjU8NjYsImlhdCI6MTQ4NzY3OTI2Niwic2NvcGUiOiJyZWFkOmRhdGEgZXh0cmEiLCJodHRwczovL2Zvby5jb20vY2xhaW0iOiKoPXIifQ.da-48mHY_7esfLZpvHWWL8sIH1j_2mUYAB49c-B472lCdsNFvpaLoq6OKQyhnqk9_aW_Xhfkusos3FECTrLFvf-qwQK70QtwbkbVye_IuPSTAYdQ2T-XTzGDm9Nmmy5Iwl9rNYLxVs2OoCdfpVMyda0OaI0AfHBgEdKWluTP67OOnV_dF3KpuwtK3dPKWTCo2j9VCa7X1I4h0CNuM79DHhY2wO7sL8WBej7BSNA3N2TUsp_YTWWfrvsr_vVhJf-32G7w_12ms_PNFUwj2C30ZZIPWc-uEkDztyMLdI-lu9q9TLrLdr0dOhfrtfkdeJx4pUSiHdJHf42kg7UAVK6JcA",
  "expires_in": 86400,
  "scope": "extra",
  "token_type": "Bearer"
}

​
Decode token

The easiest way to decode the access token and review its contents is to use the JWT.io Debugger. Copy your access token and paste it into the editor. The is decoded automatically and its contents are displayed. Note that the last two items of the Payload have both been set by your hook:
  • "scope": "extra"
  • "https://foo.com/claim": "bar"

​
Learn more