JWT claims, explained.

What each registered, OAuth and OpenID Connect claim means, which ones your API must check, and what never belongs in a token.

By the NestedBit team · Updated

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 iss and sub together.
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 scp instead.
roles, groups, entitlements
What the subject holds, when the issuer includes it. Auth0 adds a permissions array 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 JWT or at+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

  1. The signature, with the algorithm pinned in configuration.
  2. exp and nbf, with no more than a minute of clock leeway.
  3. iss: one of the issuers you trust.
  4. aud: this API.
  5. typ: at+jwt where your issuer sets it, so an ID token can’t pass as an access token.
  6. Only then, sub, scope and roles, to decide what the caller may do.

Free tool · No sign-up

JWT Decoder and Security Inspector

A JWT decoder that runs in your browser and shows what's wrong with a token's claims and signing.

Starts with a free 30-minute intro call, or email hello@nestedbit.com.