JWT Claims Reference Guide: Standard, Private, and Reserved Claims Explained

Overview

If you want one clear mental model for JWT payloads, start here: a claim is just a piece of information asserted inside the token. The payload is not a random bag of fields. It is a contract between the token issuer, the token consumer, and the systems that rely on it.

In practice, JWT claim design affects more than readability. It influences authorization behavior, incident response, privacy exposure, token size, interoperability, and long-term maintainability. A token that “works” in one service may still be poorly designed if its claims are ambiguous, overloaded, or impossible to validate consistently.

For most teams, JWT claims fall into three broad buckets:

• Registered or standard claims: commonly recognized names such as iss, sub, aud, exp, nbf, iat, and jti.
• Public claims: names intended to avoid collisions, often namespaced when shared across systems.
• Private claims: custom claims agreed upon between specific parties for a specific application.

You will also hear people describe some names as “reserved JWT claims.” Usually they mean the registered claims defined by the JWT specification, or names that should not be casually repurposed because doing so breaks assumptions in validators, libraries, or downstream services.

A useful rule of thumb is this: standard claims describe token context, while private claims describe application context. Mixing the two is one of the most common causes of fragile token designs.

Core framework

This section gives you a working framework for reading and designing JWT claims confidently.

1) Understand what each standard claim is for

Here is the practical JWT claims list most developers revisit.

• iss — Issuer. Identifies who created the token. This should be stable, specific, and validated exactly by the consumer. If your services trust multiple issuers, the accepted list should be explicit.
• sub — Subject. Identifies the principal the token refers to, often a user ID, service account ID, or device ID. The main pitfall is assuming sub is globally unique without issuer context. In many systems, uniqueness only exists for the pair iss + sub.
• aud — Audience. Identifies the intended recipient or relying party. This is one of the most important claims for preventing token replay across services. A token meant for API A should not be quietly accepted by API B.
• exp — Expiration time. The point after which the token should no longer be accepted. Keep in mind that short-lived tokens reduce risk, but only if all validators actually enforce expiration.
• nbf — Not before. The earliest time at which the token becomes valid. This is useful for staged validity or time-bound workflows, but can produce debugging friction when clocks drift.
• iat — Issued at. Indicates when the token was created. Helpful for age checks, session reasoning, and troubleshooting, but not a substitute for exp.
• jti — JWT ID. A unique identifier for a token instance. Commonly used for replay detection, revocation tracking, or audit correlation.

These claims are widely used because they express properties validators can reason about consistently. They are not mandatory in every token, but every omission should be intentional.

2) Separate identity, authorization, and metadata

One of the easiest ways to keep a JWT payload explained clearly is to sort claims into three categories:

• Identity claims: who the subject is. Example: sub, tenant ID, username surrogate, device ID.
• Authorization claims: what the subject can do. Example: roles, scopes, permissions, entitlements.
• Metadata claims: how the token should be processed. Example: iss, aud, exp, token version, authentication method.

Problems appear when one claim tries to do all three jobs. A field called user that sometimes contains an ID, sometimes an email, and sometimes a display name is a future incident waiting to happen.

3) Treat private claims as API design, not convenience fields

Custom JWT claims often start as shortcuts. A team wants to avoid another database lookup, so it adds department, featureFlags, country, isAdmin, and several UI preferences to every token. Over time, other services begin to depend on those values. Eventually the token becomes an undocumented distributed contract.

A better approach is to define private claims deliberately:

• Use stable names.
• Document expected types.
• Define which services may rely on each claim.
• Version behavior when semantics change.
• Avoid embedding data that changes more often than the token lifetime can tolerate.

If a claim can become stale quickly, it may belong in a lookup-backed authorization check instead of the token.

4) Avoid collisions with namespaced public claims

When tokens move across teams, vendors, or federated systems, generic custom names like role, tenant, or id become risky. They may collide with another issuer’s conventions or be interpreted differently by downstream consumers.

For shared ecosystems, namespaced public claims are often easier to manage. Instead of a vague key, use a URI-style namespace or another collision-resistant naming strategy. The exact convention depends on your platform, but the principle is durable: a claim name should say where it comes from and what it means.

5) Remember that JWT payloads are visible unless otherwise protected

Many debugging and security mistakes come from treating a JWT as if it were an encrypted container. A signed JWT protects integrity, not secrecy. If someone can read the token, they can usually decode the payload. That means sensitive personal data, internal system hints, and unnecessary profile attributes should not be placed in claims casually.

For digital identity workflows, this matters directly. Tokens frequently move through browsers, mobile apps, logs, support tools, proxies, and developer utilities. If a field would create privacy or compliance concerns when exposed, do not assume a JWT is the right place to store it.

For teams comparing tools and workflows, our guide to Best JWT Decoder Tools Compared: Features, Security, and Developer Workflow is a useful companion when deciding how to inspect tokens safely.

Practical examples

The fastest way to understand custom JWT claims is to compare good and bad patterns.

Example 1: Access token for an internal API

{
  "iss": "https://auth.example.internal",
  "sub": "user_12345",
  "aud": "billing-api",
  "exp": 1735689600,
  "iat": 1735686000,
  "jti": "7fa2c8d1-...",
  "scope": "invoice:read invoice:write",
  "tenant_id": "tenant_9"
}

Why this works:

• iss, aud, and exp support reliable validation.
• sub identifies the subject without relying on mutable data like email.
• scope expresses delegated capabilities clearly.
• tenant_id adds application context that may be necessary for multi-tenant enforcement.

What to verify:

• The API validates the exact audience.
• Tenant isolation does not rely on the client choosing a tenant arbitrarily.
• Scopes are interpreted consistently across services.

Example 2: ID token overloaded with authorization logic

{
  "iss": "https://id.example.com",
  "sub": "abc123",
  "aud": "web-client",
  "exp": 1735689600,
  "email": "person@example.com",
  "name": "A. Person",
  "is_admin": true,
  "can_refund": true,
  "dashboard_theme": "dark"
}

This may work in a small system, but it mixes identity display attributes, authorization decisions, and user preferences. That creates several risks:

• UI fields become coupled to auth middleware.
• Privilege changes may not take effect until old tokens expire.
• Downstream services begin trusting claims that were only intended for presentation.

A better design is often to keep the ID token focused on identity assertions and issue a separate access token or perform server-side permission checks for high-risk actions.

Example 3: Safer private claim naming

Suppose multiple partner services consume tokens from your platform. Instead of generic keys like role or account_id, you might define claims with a clear namespace and schema policy. The exact syntax varies, but the important point is that claim ownership is obvious, and semantics are documented. This reduces ambiguity during federation and debugging.

Example 4: Device or workflow tokens

JWTs are not only for end-user sessions. They also appear in device identity, QR links, handoff flows, and deep-link exchanges. In those cases, claims often represent transaction state rather than a human user.

For example, a short-lived handoff token might include:

• iss for the broker service
• aud for the receiving app
• exp with a very short lifetime
• jti for one-time use tracking
• a custom handoff_id or workflow reference

If you work on app-to-app identity transitions, see Designing Secure Deep-Link Handoffs from AI Assistants to Retail Apps for related design considerations.

Example 5: Revocation-aware design

Teams sometimes ask whether jti is required. Not always. But if you need to invalidate specific tokens, detect replay, or correlate incidents, a token identifier becomes very useful. The tradeoff is operational: once you rely on jti, you usually need supporting storage, cache, or event infrastructure to make revocation meaningful.

Common mistakes

If you remember only one section from this guide, make it this one. Most JWT production problems come from a small set of repeatable mistakes.

Using JWTs as mini databases

Every extra claim increases size, exposure, and coupling. Put only the information in the token that consumers truly need at decision time.

Trusting unvalidated claims

A payload can look correct in a JWT decoder and still be unsafe to trust. Validation must include signature integrity, issuer, audience, time-based claims, and any application-specific checks.

Repurposing standard claims

Do not overload sub to hold a display name, or aud to hold a tenant, or iss to represent an environment label. Registered claims have expected meanings. Reusing them for unrelated business data creates subtle breakage.

Assuming custom claims are self-explanatory

Fields like role, groups, and permissions sound clear but are often interpreted differently by different services. Define exact formats and semantics. Is role singular or plural? Are groups for UI filtering or access control? Is permission evaluation additive or deny-first?

Embedding sensitive personal or regulated data

JWTs often travel farther than expected. Avoid placing secrets, high-sensitivity personal information, or detailed internal status fields in tokens unless you have a strong reason and the correct protections.

Ignoring clock skew

exp, nbf, and iat look straightforward until distributed systems disagree about time. Small validation leeway may be appropriate, but it should be intentional and limited.

Letting stale authorization linger

If permissions change frequently, long-lived tokens can leave users with old access states. Consider shorter lifetimes, refresh strategies, or introspection-based checks for high-risk actions.

Failing to document claim contracts

A JWT payload explained in code comments alone is not enough. When multiple teams consume the same token, undocumented claims become operational debt. Maintain a claim registry, even if it is lightweight.

For teams building broader visibility into identity flows, You Can't Protect What You Can't See: Building an Identity-Centric Visibility Platform complements this topic well.

When to revisit

JWT claim design should not be treated as finished once a token ships. Revisit your claim model whenever the surrounding trust model changes.

Use this practical review checklist:

• When the primary auth flow changes: moving from session-based auth to token-based auth, adopting passwordless flows, adding machine identities, or introducing mobile handoffs usually changes which claims are necessary.
• When a new service consumes the token: every new audience increases the cost of ambiguous claim definitions.
• When you add federation or third-party integrations: namespacing, collision avoidance, and issuer validation become more important.
• When permissions become more granular: reassess whether current role or scope claims still map cleanly to policy decisions.
• When privacy requirements tighten: remove unnecessary user data from payloads and review logging and support workflows around tokens.
• When incident response reveals replay or misuse: consider whether aud, jti, token lifetime, or revocation support need improvement.
• When standards, libraries, or tooling change: validation defaults differ across frameworks, and new tools may expose weak assumptions in your existing design.

If you want an action-oriented maintenance habit, schedule a recurring token contract review. For each token type in your environment, answer five questions:

1. Who issues it?
2. Who is allowed to accept it?
3. Which claims are required for validation?
4. Which custom claims are relied upon for authorization or routing?
5. Which claims could be removed without breaking the workflow?

That exercise usually reveals unnecessary payload bloat, weak audience checks, and undocumented dependencies.

As your broader identity stack evolves, related patterns in passwordless login, app handoffs, and wallet-based identity may also reshape claim design. Articles like Magic Links, OTPs, and Passcodes: Designing Passwordless Journeys for Global Users and Extending Mobile Wallets to Third‑Party Keys: Interoperability, Federation, and Trust Models are worth reviewing when your token ecosystem expands.

The bottom line is simple: JWT claims are not just fields in a payload. They are part of your identity contract. Keep standard claims standard, keep private claims disciplined, validate every assumption, and revisit the model whenever your trust boundaries move.