Claim

A claim is a name/value pair in a JWT payload that asserts something about the token’s subject. Claims are JSON properties; the payload is a JSON object of them. Standard claims defined in RFC 7519 §4:

• iss — Issuer: who created the token.
• sub — Subject: who the token is about (typically a user ID).
• aud — Audience: who the token is intended for. Can be a string or array.
• exp — Expiry: Unix seconds after which the token must be rejected.
• iat — Issued At: Unix seconds when the token was created.
• nbf — Not Before: Unix seconds before which the token is invalid.
• jti — JWT ID: a unique identifier for revocation tracking.

Beyond the standard set, applications add their own claims: role, email, tenant_id, permissions, etc. RFC 7519 doesn’t restrict what custom claims look like, though IANA maintains a registry of well-known names to prevent collisions.

Three classes of claims worth distinguishing: registered (the seven above, IANA-managed), public (registered with IANA or namespaced under a URI to avoid clashes), and private (mutually-agreed between issuer and consumer; no namespacing).

Decode and inspect every claim in a JWT with our JWT decoder. It surfaces the standard claims separately and shows time-to-expiry against your machine’s current time.

Custom-claim namespacing — the standard practice: when an application adds custom claims that may later be embedded in a token shared between vendors, prefix them with a URI you own. Auth0 uses https://yourdomain.com/claims/role; AWS Cognito uses cognito:groups. Bare names like role or permissions are convenient but risk colliding with future IANA-registered claims and with other vendors’ conventions. OpenID Connect specifies certain conventional names (email, name, given_name, family_name, picture, locale) that have stable meanings across identity providers — these are safe to use as-is in any OIDC-compliant flow. Reference: IANA JSON Web Token Claims Registry.

A worked example: validating exp and nbf

Consider a JWT payload {"sub":"42","iat":1716220800,"exp":1716224400,"nbf":1716220800}. The token was issued at Unix timestamp 1716220800 (2024-05-20 16:00:00 UTC), is valid starting immediately, and expires at 1716224400 (2024-05-20 17:00:00 UTC) — a one-hour lifetime. A correct verifier reads the current Unix time, rejects the token if now ≥ exp (with optional small leeway, typically 30-60 seconds, to absorb clock skew across services), and rejects if now < nbf. RFC 7519 §4.1.4 mandates that exp processing “MUST” account for clock skew but leaves the tolerance to the implementer. A 60-second leeway is the de-facto industry default; jose, jsonwebtoken, and pyjwt all use 0-60s configurable windows.

Why it matters: the security implications

Most JWT security incidents trace back to claim validation omissions, not cryptographic failures. The 2018 Auth0 CVE-2018-0114 advisory documented libraries that verified the signature but skipped exp, allowing replay of stolen tokens indefinitely. Several frameworks have shipped with default verifiers that ignore aud, letting a token minted for one service be accepted by another in the same trust domain. Best practice: always verify the full set of standard claims that apply (iss, aud, exp, nbf, plus signature and algorithm allow-list) — every library exposes these as constructor or verify-call options, and the cost of enabling them is essentially zero. Reference: RFC 8725 — JSON Web Token Best Current Practices.