How to Decode an Auth0 JWT: Claims, Namespacing, and Inspection
- Auth0 JWT structure: what claims Auth0 always includes
- Why Auth0 requires namespaced custom claims and how to read them
- How to decode an Auth0 access token vs ID token
- Checking roles and permissions in an Auth0 JWT
Table of Contents
Auth0 issues two types of JWTs: an ID token (user identity) and an access token (API authorization). Both can be decoded to read claims — paste either one into the decoder above. Here is what you will find and how Auth0 structures its tokens.
Auth0 ID Token vs Access Token
Auth0 issues two JWTs after a successful login:
- ID token: Contains user identity information — sub, email, name, picture, email_verified. Used by your frontend to show user info. Should NOT be used to authorize API calls.
- Access token: Used to call your API. Contains sub, aud (your API identifier), scope, and any custom claims you have configured. Verify this on your API server.
Both are JWTs and both can be decoded with the tool above. The ID token is typically signed with RS256 using Auth0's public key. The access token may be opaque (not a JWT) unless you have configured a custom API in Auth0.
Claims You Will See in an Auth0 JWT
A typical Auth0 ID token payload contains:
{
"sub": "auth0|64f3a1b2c3d4e5f6a7b8c9d0",
"name": "Jane Smith",
"email": "[email protected]",
"email_verified": true,
"picture": "https://s.gravatar.com/...",
"nickname": "jane",
"iss": "https://YOUR-DOMAIN.auth0.com/",
"aud": "YOUR-CLIENT-ID",
"iat": 1700000000,
"exp": 1700003600,
"nonce": "abc123"
}The sub claim format is PROVIDER|USER-ID — for example auth0|... for username/password users, google-oauth2|... for Google logins, github|... for GitHub. This tells you which identity provider authenticated the user.
Auth0 Custom Claims Must Be Namespaced
Auth0 silently strips any custom claims you add unless they use a full URL namespace. This is a common source of confusion — you add a role claim in an Auth0 Action and it never appears in the token.
The fix: use a URL you control as the namespace:
// Auth0 Action (correct)
exports.onExecutePostLogin = async (event, api) => {
const namespace = 'https://myapp.com';
api.idToken.setCustomClaim(namespace + '/role', event.user.app_metadata.role);
api.accessToken.setCustomClaim(namespace + '/role', event.user.app_metadata.role);
};In the decoded token, this appears as "https://myapp.com/role": "admin". To read it in JavaScript:
const role = payload['https://myapp.com/role'];Reading Auth0 Roles and Permissions in the JWT
Auth0's RBAC system can include roles and permissions directly in the access token. Enable this in your Auth0 API settings under "RBAC Settings" — toggle "Add Permissions in the Access Token."
Once enabled, the access token payload includes:
{
"permissions": ["read:reports", "write:invoices"],
"https://YOUR-API.com/roles": ["admin", "editor"]
}Note that roles use the namespace format (URL prefix) while permissions are added directly as a top-level permissions array. Both are readable via the decoder above — paste your access token to confirm the claims are present before writing your authorization logic.
Decode Your Auth0 Token Now
Paste your Auth0 ID token or access token above — see all claims, namespaced fields, and expiry decoded instantly.
Open Free JWT DecoderFrequently Asked Questions
Why does my Auth0 access token not decode like a JWT?
Auth0 issues opaque (non-JWT) access tokens by default unless you have created a custom API in the Auth0 dashboard. Go to Applications > APIs, create an API, and set it as the audience in your auth request — Auth0 will then issue a JWT access token.
How do I find my Auth0 domain to verify the issuer?
Your Auth0 domain is in your Auth0 dashboard under Settings > Custom Domains or in any application's settings. It looks like YOUR-TENANT.auth0.com or a custom domain you configured.
Can I decode an Auth0 Management API token?
Yes. Management API tokens are JWTs. Paste them into the decoder to see the scope claim listing which management permissions were granted.
