Hello developers! 
This is Nik, one of the Community Engineers of Auth0, most probably you have seen me around the forum in the past months. In regards to the creation of our new Developer to Developer hub, I will be posting topics regularly about the Auth0’s features and how you can use them in your applications.
As you have most probably figured out from the title of the post, today we will be diving into what I believe to be one of the most important assets regarding user management within your application and that would be Custom Claims.
As most of you might already know, ID and Access Tokens are being used for token-based authentication in order to pass information about the user to the application. Within Auth0, these tokens follow the JWT (JSON Web Token) Standard. Once such a token is passed to the application after the user authenticated themselves, it will be composed of several claims, basically pieces of information about the user such as their name, email address or username. This is where custom claims come into action, via the help of an Action, you will be able to pass extra information to the token in order to customize and improve your application.
For this implementation, I will be using the React Sample Application.
To get started, firstly you would need to create a PostLogin Trigger via the Auth0 Dashboard. You will need to navigate to Actions → PostLogin Trigger → + icon on the top right → Create Custom Action. Once you have created your actions, the code to add a custom claim would look something like this:
exports.onExecutePostLogin = async (event, api) => {
//Store the namespace you are looking to use for the claim in a constant
const namespace = "https:/my-cool-name-space";
//Set the custom claim with the required data inside the ID Token
api.idToken.setCustomClaim(`${namespace}/some_random_data`, "random_data");
//Also add the custom claim to the Access Token if necessary
api.accessToken.setCustomClaim(`${namespace}/some_random_data`, "random_data");
};
You can add all sorts of information which is available in the authorization event depending on your implementation. for example, if the user who authenticates has roles assigned to them, you are able to include them as custom claims:
exports.onExecutePostLogin = async (event, api) => {
const namespace = "https:/my-cool-name-space";
if(event.authorization)
{
api.idToken.setCustomClaim(`${namespace}/user_roles`, event.authorization.roles)
}
};
Keep in mind that these custom claims will not be visible inside the ID Token on the first login that they are set. If these roles are being set via the Management API, you will need to prompt the user to re-authenticate or configure your application to perform a silent authentication once they have been assigned to the user.
Once the user has logged into the application, this is what the ID Token will contain:
{
"https:/my-cool-name-space/meta": "random_data",
"https:/my-cool-name-space/user_roles": [
"Test_One",
"Test_Two"
],
"nickname": "test_user",
"name": "test_user@test.com",
"picture": "someRandomPhoto.png",
"updated_at": "2025-09-01T18:07:53.294Z",
"email": "test_user@test.com",
"email_verified": false,
"sub": "auth0|{{auth0_user.id}}"
}
IMPORTANT NOTE
When using a NextJS Application, the client must be configured to save the additional claims added to the token otherwise they will be filtered out since they are not part of the default claims. You can read more about that in our documentation.
You will need to add the following piece of code to your application in order for any added custom claims to be included.
import { Auth0Client } from "@auth0/nextjs-auth0/server";
export const auth0 = new Auth0Client({
async beforeSessionSaved(session, idToken) {
return session;
}
});
In addition to adding the user roles to the token, if you register your API on the Auth0 Dashboard, by enabling the RBAC settings from Applications → APIs → Your_API_Name → RBAC Settings → Toggle Enable RBAC and Add Permissions To Access Token, you will also include any permissions assigned to the roles of the user. Unless your application has RBAC configured, you will need to retrieve the permissions via the Management API.
Once, RBAC has been enabled for your API, you will need to retrieve the Access Token and decode it in order to gain access to these claims. In the case of my user, the decoded access token would look something like this:
{
//Claim added via the action
"https:/my-cool-name-space/some_random_data": "random_data",
"iss": "https://{{your_auth0_domain}}.com/",
"sub": "auth0|{{auth0_user.id}}",
"aud": [
"https://{{your_api_name}}",
"https://{{your_auth0_domain}}/userinfo"
],
"iat": 1756751202,
"exp": 1756751322,
"scope": "openid profile email",
"azp": "{{auth0_client_id}}",
"permissions": [
//Permissions of the Test_Two Role
"delete:test",
"update:test",
//Permissions of the Test_One Role
"read:test",
]
}
This would be everything that you will need in order to get started in regards to setting custom claims within Auth0. This was quite a simple dive into implementing custom claims for your application, however, there are numerous approaches to this and you can expand considerably on this feature depending on your specific use-case and implementation.
If you have any questions or other features which you would like to see explained in the Developer to Developer Hub, let me know by leaving a reply or by sending me a DM!
Hope to connect with all of you soon enough! Take care developers! 
RESOURCES AND OTHER USEFUL STUFF