Use custom claims to carry only the identity and authorization data an application needs at request time, such as user IDs, roles, and limited permissions. Keep tokens small, set short expirations, and validate issuer and audience on every verification step. Do not place secrets, personal data, or data that should change frequently into the token itself.
What custom JWT claims are for, and what they are not for
Custom claims should extend a token only with data the verifier needs immediately to make an authorization or routing decision. That usually means compact, stable facts such as a subject identifier, a tenant, a role set, or a small permission flag. If a claim is not required at verification time, it belongs in your data store, not in the JWT.
That separation matters because JWTs are often copied across services, logged by intermediaries, cached in clients, and inspected by tooling. The token becomes a portability object, so every byte and every field increases exposure. Treat the claim set as part of the access contract, not as a general-purpose data container.
For teams designing token content, JWT Security Guide is the best place to anchor the core rules around validation, algorithm pinning, claim checks, and revocation handling.
How to keep claims small and safe in practice
The safest pattern is to keep the token immutable for the life of that token and to avoid placing anything in it that would become stale quickly or create a privacy problem if exposed. User names, email addresses, addresses, internal notes, API keys, and session secrets all belong outside the token. If the application needs those values, fetch them from a protected source after the token has been verified.
Limit custom claims to the minimum set that preserves authorization correctness. A role or entitlement bit is often enough; a full permissions matrix usually is not. If the claim is only useful for display logic, analytics, or convenience, it does not justify token bloat. The more claims you embed, the more often you must regenerate tokens when business data changes.
When teams need a broader identity or session pattern around tokens, Token and Session Security Guide helps distinguish what belongs in the token from what should be enforced through session lifecycle controls.
Stable claims also make auditing easier. If a claim can be trusted for the full token lifetime, the verifier can use it without repeated downstream lookups. If it changes frequently, move the source of truth out of the JWT and shorten the token lifetime instead of trying to “refresh” the claim in place.
How to avoid leaking sensitive data through JWTs
Protect JWT contents as if they may be observed, because in many architectures they can be. Even when the token is signed, the payload is only encoded, not hidden. That means putting secrets, personal data, or highly sensitive operational data into a JWT creates avoidable exposure if the token is intercepted, logged, forwarded, or copied into telemetry.
Use issuer and audience validation on every verification step, and reject tokens that arrive in the wrong context. That reduces the chance that a token minted for one system is reused in another. If you need stronger resilience against replay or token theft, choose sender-constrained patterns rather than increasing token complexity with extra embedded data. For implementers handling access-token design, the RFC 8707: Resource Indicators for OAuth 2.0 and RFC 9449: OAuth 2.0 Demonstrating Proof of Possession (DPoP) are useful references for audience restriction and token binding.
If your environment uses OAuth access tokens or token exchange flows, OAuth Token Introspection and Revocation Guide is a practical reference for deciding when to validate centrally and when to revoke rather than overstuff a token with mutable state.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP ASVS and NIST SP 800-53 Rev 5 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| OWASP ASVS | V9 — Self-contained Tokens | Custom JWT claims and token size directly affect self-contained token safety. |
| Recommendation — Keep JWT payloads minimal and avoid embedding sensitive or mutable data. | ||
| NIST SP 800-53 Rev 5 | IA-5 — Authenticator Management | JWT lifetimes, validation and revocation depend on credential and token lifecycle control. |
| IA-9 — Service Identification and Authentication | JWT claims often carry service-facing authentication context for API and workload verification. | |
| AC-6 — Least Privilege | Only the minimum authorization data needed at request time should be present in the token. | |
| Recommendation — Set short token lifetimes and rotate or revoke token material promptly. Bind token use to the intended service and verify issuer and audience on every request. Limit claims to the least privilege needed for the current request. | ||
Practitioner Guidance
What to verify: Confirm that every custom claim has a direct verification-time purpose and that no claim duplicates data already available from a trusted lookup. If you cannot explain why the verifier needs the field, remove it.
Common mistake: Teams often treat JWT payloads like a convenient profile store and then discover that the same token is copied into logs, browser storage, API gateways, or support tooling. That is how low-value convenience data becomes an exposure issue.
Decision rule: If the field is sensitive, volatile, or only needed by a downstream service that can query a source of truth, do not embed it in the token. Prefer a smaller token plus a controlled lookup over a larger token with broader blast radius.
Practitioner takeaway: The right design is usually a narrow, stable JWT that proves identity and carries only the minimum authorization context, while everything else stays in systems that can be updated, protected, and audited independently.
Related resources from NHI Mgmt Group
Deepen Your Knowledge
Free weekly newsletter
Subscribe to the NHI & AI Identity Journal
The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.
Bonus 33% off our NHI Course when you subscribe.
Reviewed and updated by the NHIMG editorial team on October 31, 2026.
NHI Mgmt Group — the #1 independent authority on Non-Human Identity, IAM, and Agentic AI security. nhimg.org