Every JWT claim a developer touches, the seven registered claims from RFC 7519, the OpenID Connect identity claims, OAuth 2.0 access token claims, and the de-facto conventions used by Auth0, Clerk, Okta, and Azure AD.
The seven base claims defined by RFC 7519. Optional individually, but iss, sub, aud, and exp should always be present on production tokens.
Identity claims defined by the OpenID Connect Core spec. Appear in ID tokens issued by OIDC providers.
Access token claims standardized by RFC 9068 (JWT Profile for OAuth 2.0 Access Tokens). Used in resource-server authorization.
Claims that are not formally standardized but have become de-facto conventions across major identity providers.
Custom claims private to a specific issuer. Must be namespaced to avoid collision with future standard claims.
issIssuerStringOrURIRFC 7519 §4.1.1Identifies the principal that issued the JWT. Usually a URL, the authorization server's base URL, but can be any case-sensitive string unique to the issuer.
"iss": "https://accounts.google.com"Developer note: Validate this on every verification. Mismatch means a token signed by a different issuer is being replayed against your service.
subSubjectStringOrURIRFC 7519 §4.1.2Identifies the principal that is the subject of the JWT, typically the user the token represents. Must be unique within the issuer's namespace, or globally unique.
"sub": "user_42c9bb"Developer note: Treat sub + iss as the composite user identity. A raw sub by itself is meaningless across issuers.
audAudienceStringOrURIRFC 7519 §4.1.3Identifies the recipients the JWT is intended for. May be a single string or an array. Recipients reject the token if their identifier is not in the audience list.
"aud": "https://api.alldevtoolshub.com"Developer note: Always validate aud, a missing check lets an access token for service A be replayed against service B (the 'confused deputy' attack).
expExpiration TimeNumericDateRFC 7519 §4.1.4Time after which the JWT must not be accepted, expressed as seconds since the Unix epoch (UTC). Verifiers reject tokens where current time ≥ exp.
"exp": 1735689600Developer note: Always require this claim on access tokens. Recommended lifetime: 5–15 minutes for access tokens, longer for refresh tokens.
nbfNot BeforeNumericDateRFC 7519 §4.1.5Time before which the JWT must not be accepted. Allows for tokens valid only at or after a future point in time.
"nbf": 1735603200Developer note: Rare in practice. When used, allow a small leeway (30–60s) to absorb clock skew between issuer and verifier.
iatIssued AtNumericDateRFC 7519 §4.1.6Time at which the JWT was issued, expressed as seconds since the Unix epoch (UTC). Useful for computing token age.
"iat": 1735689000Developer note: Use this for replay detection in long-lived sessions, reject tokens older than your maximum session length even if exp has not passed yet.
jtiJWT IDstringRFC 7519 §4.1.7Unique identifier for the JWT. Lets the recipient track which tokens have been used and prevent replay.
"jti": "a45f6b1c-2d3e-4f5a-9b8c-7d6e5f4a3b2c"Developer note: Required for stateful revocation. Store consumed jti values in a short-TTL cache (Redis) keyed by jti.
auth_timeAuthentication TimeNumericDateOIDC Core 1.0 §2Time when the end-user authentication occurred (seconds since Unix epoch). Required when a max_age request was made or when auth_time is requested as an Essential Claim.
"auth_time": 1735685400Developer note: Use this to enforce step-up authentication: if a sensitive action requires fresh auth, check that now() - auth_time < your threshold.
nonceNoncestringOIDC Core 1.0 §2Random value the client sends in the authentication request and matches in the returned ID token. Mitigates token replay during the authentication flow.
"nonce": "n-0S6_WzA2Mj"Developer note: Bind the nonce to the user's session cookie, not to the request URL. Otherwise an attacker who intercepts the redirect can forge a session.
acrAuthentication Context Class ReferencestringOIDC Core 1.0 §2Identifier for the authentication context, how strongly the user was authenticated. Values are agreed between issuer and consumer.
"acr": "urn:mace:incommon:iap:silver"Developer note: Pair with amr for full assurance. For step-up to phishing-resistant auth, require acr ≥ a documented threshold.
amrAuthentication Methods ReferencesarrayOIDC Core 1.0 §2 / RFC 8176Array of strings identifying the authentication methods used. RFC 8176 defines standard values like 'pwd', 'mfa', 'hwk', 'face', 'fpt', 'otp'.
"amr": ["pwd", "mfa", "hwk"]Developer note: Use this for fine-grained auth decisions. 'pwd' alone is weaker than 'pwd' + 'mfa'; 'hwk' (hardware key) is phishing-resistant.
azpAuthorized PartyStringOrURIOIDC Core 1.0 §2The party to which the ID token was issued. Used when the token has multiple audiences and one of them is acting as the client.
"azp": "client_app_42"Developer note: Only present when aud contains more than one value. When present, verify it matches the expected client_id.
nameFull NamestringOIDC Core 1.0 §5.1End-user's full name in displayable form, including all name parts in the user's preferred ordering.
"name": "Rahul Jain"emailEmailstringOIDC Core 1.0 §5.1End-user's preferred email address as a valid RFC 5322 addr-spec.
"email": "rahul@example.com"Developer note: Email is NOT a stable identifier, users change addresses. Use sub for user identity, email for display.
email_verifiedEmail VerifiedbooleanOIDC Core 1.0 §5.1True if the end-user's email has been verified by the issuer at the time the token was issued. Otherwise false.
"email_verified": trueDeveloper note: Reject tokens with email_verified=false for any flow that grants access based on email ownership.
preferred_usernamePreferred UsernamestringOIDC Core 1.0 §5.1Shorthand name the user wishes to be referred to as. Not guaranteed to be unique by the issuer.
"preferred_username": "rahul.j"pictureProfile Picture URLstringOIDC Core 1.0 §5.1URL of the end-user's profile picture. Must reference an image file (PNG, JPEG, GIF).
"picture": "https://lh3.googleusercontent.com/a/.../photo.jpg"scopeScopestringRFC 9068 §2.2.3Space-separated list of scopes the token bearer is authorized for. Used in OAuth 2.0 access tokens to scope down permissions.
"scope": "openid profile email read:invoices"Developer note: Treat scopes as additive permissions. Always check the scope claim before authorizing scope-gated actions.
client_idClient IDStringOrURIRFC 9068 §2.2OAuth 2.0 client identifier of the application the token was issued to.
"client_id": "wb_mobile_v2"groupsGroupsarrayRFC 9068 §2.2.3.1Groups the end-user belongs to. Used for role-based access control in enterprise identity providers.
"groups": ["engineering", "billing-admins"]rolesRolesarrayRFC 9068 §2.2.3.1Roles assigned to the end-user. Common pattern for application authorization.
"roles": ["admin", "auditor"]entitlementsEntitlementsarrayRFC 9068 §2.2.3.1Fine-grained entitlements granted to the user. Use when roles/groups are not expressive enough.
"entitlements": ["report:export", "team:invite"]tidTenant IDstringAzure AD conventionIdentifier for the tenant the user belongs to in multi-tenant systems. Popularized by Azure AD; widely adopted in B2B SaaS.
"tid": "f8cdef31-a31e-4b4a-93e4-5f571e91255a"Developer note: Critical for tenant isolation. Validate that resources accessed belong to the same tenant as the token's tid.
orgOrganizationstringAuth0 / Clerk conventionOrganization the user is acting on behalf of in this session. Useful when one user belongs to multiple orgs.
"org": "acme-corp"permissionsPermissionsarrayAuth0 conventionGranular permissions granted to the user. Auth0-style alternative to scope-based authorization.
"permissions": ["read:users", "write:invoices"]https://example.com/roleCustom Namespaced ClaimstringOIDC custom-claim guidanceCustom claims should be namespaced by the issuer using a collision-resistant name, typically a URL the issuer controls.
"https://api.alldevtoolshub.com/role": "premium"Developer note: Never use bare names like 'role' or 'admin' for custom claims, they collide with future standard claims. Use a URL prefix you own.
RFC 7519 defines seven registered claims, all optional but conventional: iss (Issuer), sub (Subject), aud (Audience), exp (Expiration Time), nbf (Not Before), iat (Issued At), and jti (JWT ID). On production access tokens, iss, sub, aud, and exp should always be present and validated. nbf and iat are useful for replay defence and freshness checks; jti is required if you need stateful revocation.
iss identifies who issued the token (the authorization server). sub identifies who the token represents (the user). aud identifies who the token is for (the resource server). A token issued by https://auth.example.com for user 42 to access https://api.example.com would have iss=https://auth.example.com, sub=42, aud=https://api.example.com. The composite (iss, sub) is the globally unique user identity, a sub on its own is meaningless across issuers.
Without an aud check, an access token minted for service A can be replayed against service B if both share the same issuer. This is the 'confused deputy' attack. Every resource server must verify that its own identifier is in the aud array and reject the token otherwise. This is a top-five OAuth implementation mistake.
Yes. RFC 7519 allows three kinds of custom claim names: registered (in the IANA JSON Web Token Claims registry), public (collision-resistant strings, usually URLs the issuer controls), and private (agreed between issuer and consumer). For custom claims, always namespace them with a URL you own, e.g., https://api.alldevtoolshub.com/role rather than just role, so future standard claims don't collide.
ID tokens (OpenID Connect) describe who the user is, they carry identity claims like email, name, picture, auth_time. Access tokens (OAuth 2.0) describe what the bearer is authorized to do, they carry scope, permissions, and audience claims. Never use an ID token for API authorization, and never expose an access token to a frontend that should only know identity. Mixing the two is another top OAuth mistake.
A NumericDate is JSON number representing seconds since the Unix epoch (UTC), as defined in RFC 7519 §2. exp, nbf, iat, and auth_time are all NumericDates. They are integers, not strings, '1735689600', with quotes, is invalid. JavaScript's Date.now() returns milliseconds, so divide by 1000 before putting a value in a JWT.
Once you know the claims, the next step is decoding tokens and verifying signatures. Tools that pair with this reference: