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

Registered claims are standardized fields defined by RFC 7519, such as iss, sub, aud, exp, nbf, iat, and jti. Custom claims are application-specific fields that carry extra business or authorization context. The distinction matters because registered claims support interoperability and consistent validation, while custom claims require careful naming, governance, and agreement between the parties that process them.

Registered Claims Set the Validation Contract, Not the Business Payload

Registered claims are the small set of standard JWT fields that give every verifier the same baseline meaning for issuer, subject, audience, expiry, not-before, issued-at, and token ID. That matters because JWTs are not just containers for data; they are trust objects. When teams confuse standard claims with application data, they often weaken token validation, create inconsistent interpretation across services, or let business logic drift into fields that were never meant to carry it. The safest way to think about registered claims is as the minimum interoperability layer that should behave the same across systems.

Custom claims, by contrast, are where an application can add its own context, such as tenant scope, role hints, feature entitlements, or workflow state. The key difference is not just format, but governance: registered claims have shared semantics, while custom claims only mean what the participating systems agree they mean. For readers who want a standards baseline, the JWT specification in RFC 7519 defines the registered set.

In practice, many teams first notice the difference only after a service starts trusting a custom field as if it were a standard validation signal.

How Claims Are Used in Practice Across Issuers and Verifiers

At runtime, an issuer signs a JWT and a verifier checks both the token integrity and the meaning of its claims. Registered claims support that exchange because they are designed for common checks:

iss

identifies who minted the token,

aud

constrains who may accept it, and

exp

limits how long it remains valid. Those checks should be handled consistently by every service that accepts the token, otherwise one component may reject a token that another accepts. That consistency is the main operational value of registered claims.

Custom claims are typically layered on top after the standard validation step. They can help a product express authorisation context that is too specific for registered fields, but they should not replace the core control plane of token validation. Good practice is to define them clearly, scope them narrowly, and document which service owns their meaning. A claim such as

tenant_id

may be useful, but it only works safely if every consumer agrees whether it is informational, routing-related, or authorisation-critical. If the same claim is used for both display logic and access decisions, ambiguity follows quickly.

Validate registered claims first, before any application logic reads the rest of the token.
Treat custom claims as contract data, not free-form metadata.
Keep names specific enough to avoid collision with future standards or partner tokens.
Assume a verifier may see tokens from multiple issuers, and design claim semantics accordingly.

For teams working with machine or workload tokens, OWASP’s guidance on OWASP Non-Human Identity Top 10 is useful because claim design often affects how non-human identities are authenticated and authorised. This distinction becomes brittle when different microservices interpret the same custom claim differently, because the token still validates even when the meaning no longer does.

Where Custom Claims Create the Most Confusion

Tighter claim design often improves security, but it also increases coordination overhead, so teams must balance flexibility against semantic drift. The most common confusion appears when custom claims are treated like policy enforcement by themselves. A claim can state that a user or workload belongs to a group, but it does not prove that the group is current, authoritative, or safe to trust unless the issuer and verifier have a strong agreement around lifecycle and revocation.

Best practice is evolving toward using custom claims only for well-defined application decisions, while keeping time, audience, issuer, and subject checks in the registered set. Another common edge case is federation, where one identity provider emits claims that a downstream service was never built to interpret. In those environments, a claim may be syntactically valid yet operationally meaningless. Teams also need to watch for namespace collisions, especially when multiple products inject similar fields such as

role

groups

, or

permissions

When custom claims drive authorisation, the real control is not the presence of the field but the governance behind it: who can mint it, who can change it, and how quickly consumers notice when its meaning shifts. That is why registered claims are usually stable and portable, while custom claims remain local to a trust relationship or application boundary.

Risk and Threat Considerations

Custom claims can become a trust-abuse vector when services treat application-specific data as if it were an authoritative security decision. The risk is not that custom claims exist, but that downstream systems may over-trust them, especially in federated, multi-service, or workload-token environments.

Failure mechanism: The weakness appears when a verifier skips or weakens registered-claim validation, then uses a custom field for access control, routing, or privilege assignment without strong issuer, audience, and lifecycle checks. Attackers do not need to forge the JWT algorithmically if they can obtain a legitimately signed token with overbroad or stale claims, or if one service propagates a claim that another service interprets too generously.

Impact: The result can be privilege inflation, tenant boundary failure, confused-deputy behaviour, or inconsistent authorisation across services. In token-heavy systems, that turns a small semantics mistake into a cross-system access problem.

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 and MITRE ATT&CK address the attack and risk surface, while CIS Controls v8, NIST CSF 2.0 and NIST Zero Trust (SP 800-207) 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 Management	JWT claims often carry machine identity context and authorization data.
Recommendation — Restrict custom token claims that influence machine access and validate their trust boundaries.
CIS Controls v8	6 — Access Control Management	Claim misuse can translate directly into overbroad access decisions.
Recommendation — Enforce least privilege by validating token claims before any access grant.
NIST CSF 2.0	PR.AC-7 — Identity Management, Authentication, and Access Control	JWT claim validation is part of trustworthy identity and access enforcement.
Recommendation — Verify issuer, audience, and expiration before accepting claims for authorization.
NIST Zero Trust (SP 800-207)	AC-3 — Access Enforcement	Zero trust requires explicit, context-based authorization from token assertions.
Recommendation — Apply explicit authorization checks instead of trusting custom claims alone.
MITRE ATT&CK	T1550 — Use Alternate Authentication Material	Stolen or misused JWTs can be used as authentication material.
Recommendation — Monitor for abuse of bearer tokens and invalidate compromised tokens quickly.

Practitioner Guidance

What to verify: Confirm that every service validates

iss

aud

exp

, and any other required registered claims before reading custom claims for business logic. If a custom claim influences access, verify that its issuer, ownership, and refresh path are documented and testable.

Decision rule: If a claim is needed for security enforcement, define it as part of an explicit trust contract and review it like an interface change; if it is only descriptive, keep it out of access decisions. Treat ambiguous names such as

role

scope

as high-risk unless their semantics are tightly bounded.

What good looks like: Registered claims are enforced uniformly across all verifiers, custom claims have a named owner and documented meaning, and no service depends on a claim whose source or freshness it cannot explain. The practical objective is not to minimise the number of claims, but to make every claim either universally understood or deliberately local.

Practitioner takeaway: The most important judgement is to separate token validity from token meaning: registered claims should prove the token is trustworthy enough to inspect, while custom claims should only express context that the receiving system is explicitly prepared to govern.