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.
Why custom JWT claims work best as compact request-time context
Custom claims are most useful when they help the relying application make an immediate access or routing decision without another lookup. That usually means stable identifiers, coarse roles, tenant context, or a small set of authorization flags. Once claims start carrying profiles, full entitlements, or mutable business data, the token becomes harder to secure, harder to verify, and more likely to create stale decisions.
Keeping the payload lean also improves interoperability. JWTs are often forwarded through APIs, gateways, browsers, and logs, so every extra byte increases transmission overhead and the chance that the token is copied into places it should not be. The practical goal is not to stuff the token with everything the application knows, but to carry only what the verifier genuinely needs at the moment of validation.
For teams dealing with identity-heavy systems, the failure mode is often familiar: claims are treated as a general-purpose data container instead of a security artifact. That shift turns a signed assertion into a convenience layer for application state, which is where token bloat, stale authorization, and accidental disclosure begin. NHIMG’s Ultimate Guide to NHIs is useful here because it frames the broader identity and access context in which over-permissive or overstuffed token patterns tend to show up.
What to keep out of custom claims
Secrets should never be embedded in a JWT, even if the token is signed and transported over TLS. A signature preserves integrity, not confidentiality. Anyone who can inspect the token can read its claims, so putting API keys, session secrets, refresh material, private user details, or internal reference data into the payload creates exposure that survives normal verification controls.
Teams should also avoid putting fast-changing data into claims when the application depends on that data being current. Examples include dynamic entitlements, account status, policy exceptions, and temporary approvals. If those values change after issuance, the token can continue to authorize actions based on outdated information until it expires or is replaced. That is especially risky when a token is reused across multiple services or cached at the edge.
Secret sprawl is the adjacent operational trap: once teams start embedding sensitive material in tokens, that same material often ends up mirrored in logs, browser storage, debugging traces, analytics, or downstream systems. NHIMG’s Guide to the Secret Sprawl Challenge is a strong companion reference because it highlights how quickly sensitive material escapes intended control boundaries once it is copied into places that are easy to inspect and hard to revoke.
For concrete incident patterns, the Internet Archive breach and the Vercel Context.ai OAuth supply chain breach both illustrate the damage that follows when tokens or token-like credentials are too broadly exposed or too loosely governed.
Operational guardrails for token size, validation, and lifecycle
Short expirations matter because custom claims are only as trustworthy as the time window in which they remain valid. If the token carries a role, scope, or entitlement snapshot, the shorter the lifetime, the smaller the window in which stale authorization can persist. That is why teams should treat claim design and expiration design as the same control decision, not as separate concerns.
Validation must also be consistent. Each verification step should check issuer and audience so a token minted for one system cannot be replayed in another, and each service should reject claims it does not explicitly understand. Custom claims should be versioned and documented so downstream teams know which fields are authoritative and which are advisory only.
When teams need more context than a token can safely hold, the better pattern is to keep the JWT as a compact assertion and fetch mutable or sensitive data from a controlled back-end source after verification. That preserves token portability while avoiding the common mistake of using the token itself as a data store. NHIMG’s 52 NHI Breaches Analysis is a useful reminder that credential and token misuse often becomes incident material when tokens are overbroad, overexposed, or insufficiently bounded.
Standards & Framework Alignment
This section maps relevant standards and security frameworks to the operational risks and controls described in this guidance.
OWASP Non-Human Identity Top 10 address the attack and risk surface, while CIS Controls v8, NIST CSF 2.0 and NIST SP 800-63 set the governance and control requirements practitioners need to meet.
| Framework | Control / Reference | Relevance |
|---|---|---|
| OWASP Non-Human Identity Top 10 | NHI-01 — Secrets and Credential Exposure | JWTs must not carry secrets or tokens that become exposed on inspection. |
| NHI-03 — Token and Credential Rotation | Short expirations limit the impact of stale or overused token claims. | |
| NHI-05 — Least Privilege and Excessive Permissions | Custom claims should convey only the minimum authorization context needed at request time. | |
| Recommendation — Keep secrets and high-value credentials out of JWT claims. Use short-lived tokens to reduce stale authorization risk. Limit claims to the smallest permission set the app needs. | ||
| CIS Controls v8 | 5 — Account Management | JWT claims often encode account and access context that must be tightly governed. |
| 6 — Access Control Management | Issuer, audience, and claim minimization are access-control safeguards for token use. | |
| Recommendation — Minimize embedded access context and keep account data authoritative. Validate token scope and audience before granting access. | ||
| NIST CSF 2.0 | PR.AC-4 — Access Permissions and Authorizations | Custom claims should support least-privilege authorization decisions. |
| PR.DS-1 — Data-at-Rest Protection | Sensitive data should not be placed into portable tokens that may be copied or logged. | |
| PR.AC-7 — User and Device Authentication | Issuer and audience validation are core checks before trusting a JWT assertion. | |
| Recommendation — Constrain token claims to the authorization data needed by the service. Avoid embedding sensitive data in portable token payloads. Verify issuer and audience on every token validation step. | ||
| NIST SP 800-63 | 5.2 — Assertion Protection | JWTs are signed assertions whose acceptance depends on proper validation and bounded use. |
| 5.1.5 — Assertion Expiration | Short token lifetimes reduce the window for replay and stale claim use. | |
| Recommendation — Protect assertions by validating intended audience and lifetime. Set short assertion lifetimes for claims-based tokens. | ||
Practitioner Guidance
What to verify: Confirm that every custom claim has a clear consumer and a clear decision it supports at request time. If no verifier can name the exact authorization or routing use case, the claim probably does not belong in the token.
Decision rule: If the value is sensitive, mutable, or useful outside the current request, keep it out of the JWT and resolve it server-side after verification. If the value is stable, non-sensitive, and needed immediately, keep it small and explicit.
What good looks like: A well-designed token carries only the minimum identity and authorization context, expires quickly, is validated for issuer and audience everywhere, and can be safely logged without exposing data that would change your security posture.
Practitioner takeaway: The safest custom claim is the one that helps a service decide, but never becomes the place where the service stores secrets, mutable state, or anything you would not want copied into every downstream system that sees the token.
Related resources from NHI Mgmt Group
- How should teams enrich JWT claims without exposing sensitive key material to the identity provider?
- How can government teams use hard tokens for MFA without giving up cloud-based administration?
- How should security teams detect custom sensitive data without relying on regex?
- How should security teams enable secure collaboration without exposing sensitive data across internal teams and external partners?
Deepen Your Knowledge
Reviewed and updated by the NHIMG editorial team on September 19, 2026.
NHI Mgmt Group — the #1 independent authority on Non-Human Identity, IAM, and Agentic AI security. nhimg.org
