Cybersecurity glossary
What is a JWT Claim?
Learn what a JWT claim is, how registered public and private claims differ, which claims matter for authorization, and how to validate claim sets safely after signature verification.
Definition
A JWT claim is a piece of information asserted in a JSON Web Token payload—such as subject, issuer, audience, or a custom role—encoded as a JSON name/value pair that verifiers may use for authentication context and authorization decisions after the token is validated.
Why JWT claims matter
A signed JWT answers “who asserted this?” Claims answer “what was asserted?” JWT claims are the payload fields that carry identity, audience, lifetime, and application-specific authorization context.
Good claim design keeps tokens small, privacy-aware, and easy to validate. Poor claim design dumps sensitive attributes into readable payloads or invents ambiguous fields that every service interprets differently.
Claim categories in JWT
Registered claims
Standard names like iss, sub, aud, exp, nbf, iat, and jti with shared meaning across systems.
Public claims
Shared claim names registered or defined to avoid collisions across organizations.
Private claims
Custom attributes agreed by issuer and APIs, such as tenant, plan, or internal roles.
Authorization claims
Scopes, roles, or entitlements consumed after cryptographic validation succeeds.
How claims move from issue to decision
Issuer authenticates the principal
Identity proofing or OAuth grant completion establishes who is acting.
Claim set is assembled
Registered and private claims are populated under issuer policy.
Token is signed or encrypted
JWS/JWE protects the claim set according to deployment needs.
Resource server verifies the token
Signature, algorithm, and issuer trust are checked first.
Claims are validated
aud, exp, nbf, and required custom claims are enforced.
Authorization uses vetted claims
APIs map subject and entitlements to object- and function-level checks.
Design trade-offs for claim sets
| Approach | Benefit | Risk |
|---|---|---|
| Minimal claims | Smaller tokens, less leakage | May need introspection for rich authZ |
| Rich embedded claims | Stateless local authorization | Stale entitlements and privacy exposure |
| Opaque reference tokens | Easy revocation and privacy | Extra dependency on auth server |
| Mixed model | Short JWT + server lookups for sensitive data | More moving parts to operate |
Claim hygiene checklist
- Verify signatures before reading any claim for security decisions.
- Always validate iss, aud, and time claims relevant to your API.
- Prefer scopes/roles issued by a trusted authorization server—not client self-assertion.
- Avoid putting passwords, raw PII, or long-lived secrets in JWT payloads.
- Document private claim names, types, and semantics for every consumer.
- Plan for claim evolution with versioning or additive fields only.
- Reject tokens missing mandatory claims for the API’s security model.
- Remember readable claims may appear in browser storage, mobile logs, and reverse proxies.
The practical takeaway
A JWT claim is an asserted attribute inside a token payload. Cryptography makes the set trustworthy; claim design and validation make it useful and safe.
Keep registered claims correct, private claims minimal and documented, and authorization logic strict after verification. Dive into individual registered claims—aud, exp, iat, iss, nbf, and sub—for field-specific guidance.
Related security terms
Claim
The broader concept of an asserted attribute in identity tokens.
Audience Claim (aud)
Restricts which resource servers should accept the token.
Expiration Claim (exp)
Limits how long a JWT remains valid.
Subject Claim (sub)
Identifies the principal the token is about.
JWT (JSON Web Token)
The token format that carries claims in its payload.
Frequently asked questions
What is a JWT claim in simple terms?
A claim is one fact inside the token—like who the user is, which app the token is for, or when it expires. After the signature checks out, APIs read those facts to make access decisions.
What are registered claims?
Registered claims are standardized names defined in RFC 7519, including iss, sub, aud, exp, nbf, iat, and jti.
What is the difference between public and private claims?
Public claims use collision-resistant names intended for shared use. Private claims are custom fields agreed between issuer and consumer, such as tenant_id or role.
Are claims encrypted?
Not in a standard signed JWT. Claims are readable unless the token is encrypted with JWE or another confidentiality control.
Should authorization trust every claim?
Only after signature and standard validations succeed—and only claims the issuer is authoritative for. Never trust client-supplied role claims without an issuer policy.
What is claim stuffing?
Putting excessive or sensitive data into JWTs. It increases privacy risk, log leakage, and token size without improving authorization quality.
Do all JWTs include the same claims?
No. Profiles like OpenID ID tokens require specific claims, while access tokens vary by authorization server design.
References
Explore authoritative guidance and frameworks related to jwt claim.
Explore every security definition
Return to the glossary to search by term, alias, starting letter, or security category.