What is the difference between registered claims and custom claims in JWTs?

Why Registered Claims and Custom Claims Serve Different Jobs in a JWT

Registered claims are the interoperability layer of a JWT. They use standard names that libraries, gateways, and identity providers already understand, so validation rules stay consistent across systems. Custom claims are the extension layer: they let an application carry extra business or authorization context, but the meaning and enforcement of those fields only exist if the parties agree on them.

That difference is practical, not cosmetic. A token can be perfectly valid as a JWT and still be ambiguous or unsafe to consume if custom claims are poorly named, overloaded, or interpreted differently by each service. Registered claims reduce that risk because their semantics are defined by the spec, while custom claims shift the burden to the application team.

How Validation Differs Between Standard and Application-Specific Claims

Registered claims usually participate in the token's core validation path. For example, iss, aud, exp, and related fields help a verifier decide whether the token was issued by the expected party, is meant for the current audience, and is still usable. Because those fields have standard meaning, they are the safest place to anchor generic JWT processing logic.

Custom claims, by contrast, are not automatically security controls. They may express tenancy, roles, product entitlements, workflow state, or other application-specific context, but they only become authoritative when the consuming service explicitly checks them. That means a custom claim should be treated as input to application logic, not as a universal substitute for server-side authorization or policy evaluation.

In practice, teams often get into trouble when they assume a custom claim behaves like a registered one. For example, a claim may be present in one service, ignored in another, or populated by a different issuer in a way that changes its meaning. That is why JWT consumers should validate the issuer, audience, expiry, and any claim-specific expectations before trusting the rest of the payload. The JWT Security Guide is useful here because it focuses on claim checks, key handling, and validation discipline rather than just token syntax.

Why Claim Design Becomes a Governance Problem

Custom claims are often where architecture decisions become governance decisions. Once a claim starts carrying authorization context, the organisation has effectively created a contract about meaning, ownership, update rules, and consumer behaviour. If that contract is undocumented or changes informally, different services can start making different access decisions from the same token.

That is especially important when custom claims are used to represent scopes, entitlements, tenant membership, or policy hints. The more a claim influences access, the more it needs a defined source of truth, a change process, and a clear rule for who is allowed to mint or modify it. The OAuth Scope Design Guide is relevant because scope naming and audience binding face the same design pressure: the field is only useful when its semantics are consistent across issuers and resource servers.

Custom claims also create an operational dependency on token consumers. If a downstream service cannot parse a claim, it may fail closed, fail open, or silently ignore the field, depending on its implementation. That makes claim governance part of resilience as much as part of authorization design. If the business meaning of a claim matters, teams should document how the system behaves when the claim is missing, stale, malformed, or issued by an unexpected source.

Risk and Threat Considerations

Custom claims expand the attack surface because they introduce application-defined meaning into a structure that many systems will accept at face value. If the issuer, signing process, or consumer logic is weak, an attacker may try to forge, replay, misroute, or overstate privileges through a claim the application trusts more than it should.

Failure mechanism: A verifier accepts a token because the JWT is structurally valid, but it fails to enforce the issuer, audience, or claim-level semantics that make a custom claim trustworthy. That can lead to privilege inflation, cross-tenant access, or inconsistent authorisation decisions across services.

Impact: The result can be unauthorized access, broken isolation between applications or tenants, and difficult-to-detect policy drift because different services may interpret the same claim differently. Where claims carry session or authority context, poor handling can also create replay and persistence risks.

Practitioner Guidance

What to verify: Confirm which claims your architecture treats as standards-based validation inputs and which are purely application-specific. If a custom claim affects access, make its issuer, consumer, and fallback behaviour explicit in design and test cases.

Common mistake: Do not let custom claims become a hidden authorization database inside the token. If the claim is authoritative, define who mints it, who can change it, and what evidence downstream services require before trusting it.

What good looks like: Registered claims handle universal token checks, while custom claims are narrowly scoped, documented, and validated only by services that understand their meaning. Consumers fail predictably when a claim is absent or inconsistent, instead of guessing.

Practitioner takeaway: Use registered claims for portable token validity and custom claims for tightly governed application context, but never confuse token content with trust unless the validation and ownership model are equally explicit.

Related resources from NHI Mgmt Group

• How should security teams govern custom claims in API tokens?
• Why do custom JWT claims create governance risk if they are not refreshed?
• Why do JWTs create risk when controls around signing and time claims are weak?
• What happens when custom claims are added at token minting time without a robust webhook validation step?