What a claim is
A JWT’s payload is a JSON object, and each name and value in it is a claim: a statement the issuer makes about the token’s subject. Here’s a typical access token payload:
{
"iss": "https://auth.example.com/",
"sub": "user_8f2c41",
"aud": "https://api.example.com",
"client_id": "web-app",
"scope": "invoices:read",
"iat": 1793174400,
"exp": 1793175300,
"jti": "0b7c3e2a-5d1f-4c8e-9a6b-2f4d8e1c7a90"
}
RFC 7519 sorts claims into three kinds. Registered claims are the seven short names defined by the standard. Public claims are registered with IANA or use names that can’t collide, such as a URL. Private claims are anything the issuer and the services agree on. To see what each claim in your own token means, paste it into the JWT Security Inspector; it explains every claim it recognises and runs in your browser.
The seven registered claims
iss· issuer- Who created and signed the token, usually a URL. Your API should accept only the issuers it trusts.
sub· subject-
Who the token is about: a user ID, or a client ID for machine-to-machine tokens. It’s unique only within its
issuer, so identify users by
issandsubtogether. aud· audience- Who the token is for, as a string or an array. Each API must find itself here. More on the JWT audience (aud) claim, and on fixing a mismatch.
exp· expiration time- The token is rejected from this time on. See Fixing “jwt expired”.
nbf· not before- The token is rejected until this time.
iat· issued at- When the token was created. It lets you set a maximum age, or reject every token issued before a password change.
jti· JWT ID- A unique ID for this token, used to spot a replayed token or revoke a single one.
RFC 7519 makes all seven optional. The profiles built on it, such as OpenID Connect and OAuth access tokens, make several of them required.
Times are seconds, not milliseconds
exp, nbf, iat and auth_time are NumericDates: seconds since
1 January 1970 UTC. Writing milliseconds by mistake gives a token that, read as seconds, lasts for thousands of years.
The current time in seconds:
Math.floor(Date.now() / 1000) // JavaScript
int(time.time()) // Python
time.Now().Unix() // Go
Instant.now().getEpochSecond() // Java
Access token claims
When an OAuth access token is a JWT, RFC 9068 sets the rules.
The header’s typ is
at+jwt, and the token must carry iss, exp, aud,
sub, client_id, iat and jti. On top of those:
client_id- The OAuth client the token was issued to, such as your web or mobile app.
scope-
The scopes granted, as one space-separated string. Microsoft Entra ID and Okta name it
scpinstead. roles,groups,entitlements-
What the subject holds, when the issuer includes it. Auth0 adds a
permissionsarray when RBAC is turned on for an API. auth_time,acr,amr- When and how the user signed in, for APIs that require a recent or stronger sign-in, such as MFA.
ID token claims
An OpenID Connect ID token tells your
app who signed in. It must carry iss, sub,
aud, exp and iat, and its aud is your app’s client ID. Never
send it to an API as an access token. Common claims besides those:
auth_time- When the user last signed in.
nonce- Ties the token to one sign-in request, to stop replays.
azp- Authorized party: the client the token was issued to.
at_hash- A hash of the access token issued alongside it.
sid- The session ID at the identity provider, used for logout.
email,email_verified- The user’s email, and whether the provider has verified it. Don’t trust an unverified email for sign-in.
name,given_name,family_name,picture- Profile details, present when the matching scopes were requested.
Header parameters
The header isn’t claims, strictly, but it’s decoded the same way and matters as much:
alg- The signing algorithm. Verifiers must accept only the one they expect, never whatever the header says.
typ- The token type, such as
JWTorat+jwt. kid- Which of the issuer’s keys signed the token, looked up in its key set (JWKS).
jwk,jku,x5u,x5c- A key, or where to fetch one. Verifiers must not trust these from the token; keys come from your configuration.
crit- Header parameters the verifier must understand, or else reject the token.
Custom claims
Use names that won’t collide with registered ones: a URL such as https://example.com/tenant_id, or a
short prefix of your own. Then keep them small, because the token travels with every request.
- Good in a token: a tenant or organization ID, a plan, a handful of coarse roles.
- Never in a token: passwords, keys or other secrets. The payload is only encoded, and anyone holding the token can read it.
- Better left out: personal data in access tokens, and long permission lists. Permissions in a token stay stale until it expires, so check fine-grained permissions on the server.
To decide which roles exist and what each may do, lay them out in an RBAC matrix. When access depends on ownership, team or amount as well as role, read RBAC vs ABAC.
Which claims your API must check
- The signature, with the algorithm pinned in configuration.
expandnbf, with no more than a minute of clock leeway.iss: one of the issuers you trust.aud: this API.typ:at+jwtwhere your issuer sets it, so an ID token can’t pass as an access token.- Only then,
sub,scopeand roles, to decide what the caller may do.