Learn how JWT claims work, explore registered, public, and private claims, and discover security best practices for implementing JSON Web Tokens in your applications.
What are JWT claims?
JSON Web Tokens (JWTs) are a compact, URL-safe means of representing claims between two parties. Claims are statements about an entity (typically the user) and additional metadata. They form the payload of a JWT and contain the actual information being transmitted.
Understanding JWT claims is essential for implementing secure authentication and authorization in modern web applications. This guide covers everything from basic claim types to advanced security practices.
JWT structure overview
Before diving into claims, it helps to understand the JWT structure. A JWT consists of three parts separated by dots: header, payload, and signature.
- Header: Contains the token type (JWT) and signing algorithm (e.g., HS256, RS256)
- Payload: Contains the claims (the data you want to transmit)
- Signature: Verifies the token has not been tampered with
- Format: xxxxx.yyyyy.zzzzz (Base64URL encoded)
Registered claims (RFC 7519)
Registered claims are predefined claims recommended by the JWT specification. They are not mandatory but provide a standardized set of useful, interoperable claims.
- iss (issuer): Identifies who issued the JWT (e.g., "https://auth.example.com")
- sub (subject): Identifies the principal subject of the JWT (e.g., user ID)
- aud (audience): Identifies the recipients the JWT is intended for
- exp (expiration time): Unix timestamp after which the JWT must not be accepted
- nbf (not before): Unix timestamp before which the JWT must not be accepted
- iat (issued at): Unix timestamp when the JWT was issued
- jti (JWT ID): Unique identifier for the JWT to prevent replay attacks
Public claims
Public claims are custom claims that can be defined by anyone using JWTs. To avoid collisions, they should be defined in the IANA JSON Web Token Registry or use collision-resistant names like URIs.
- email: User email address (commonly used but not registered)
- name: User display name
- picture: URL to user profile picture
- https://example.com/is_admin: Namespace-prefixed custom claim
- Use IANA registry names when available for interoperability
Private claims
Private claims are custom claims created for sharing information between parties that agree on their use. They are neither registered nor public claims.
- user_id: Application-specific user identifier
- role: User role or permission level
- organization_id: Multi-tenant application identifier
- permissions: Array of specific permissions
- Use clear, descriptive names that do not conflict with registered claims
Expiration and time-based claims
Time-based claims are critical for token security. They control when tokens become valid and when they expire.
- exp (expiration): Always set this claim. Short-lived tokens (15-60 minutes) are more secure
- iat (issued at): Useful for determining token age and detecting stale tokens
- nbf (not before): Prevents tokens from being used before a specific time
- All time claims use Unix timestamps (seconds since January 1, 1970 UTC)
- Account for clock skew between servers (typically 30-60 seconds tolerance)
Common JWT claim patterns
Here are typical claim configurations for different use cases.
- Access token: Short exp (15 min), includes sub, aud, scope/permissions
- Refresh token: Longer exp (7 days), minimal claims, jti for revocation
- ID token (OIDC): Includes user profile claims (name, email, picture)
- Service-to-service: Includes iss, aud, iat, exp for API authentication
Security best practices for claims
Proper claim handling is essential for JWT security. Follow these practices to protect your applications.
- Never store sensitive data in claims (passwords, credit cards, PII)
- Always validate exp, iat, and nbf claims on the server
- Verify the iss claim matches your expected issuer
- Check the aud claim to ensure the token is meant for your service
- Use jti for token revocation and replay attack prevention
- Keep payload size small since JWTs are sent with every request
Choosing the right signing algorithm
The algorithm you choose affects both security and architecture. Understanding the options helps you make the right choice.
- HS256 (HMAC): Symmetric key, simple but requires shared secret
- RS256 (RSA): Asymmetric keys, issuer has private key, verifiers use public key
- ES256 (ECDSA): Asymmetric, smaller keys than RSA with equivalent security
- Never use "none" algorithm in production
- RS256/ES256 are preferred for distributed systems where multiple services verify tokens
Token expiration strategies
Choosing the right expiration time involves balancing security and user experience.
- Short-lived access tokens (15-60 minutes): Limits exposure if token is compromised
- Longer refresh tokens (days/weeks): Enables seamless re-authentication
- Sliding expiration: Extends token life with activity
- Absolute expiration: Forces re-authentication after fixed time regardless of activity
- Consider your threat model when choosing expiration times
Token revocation strategies
JWTs are stateless by design, making revocation challenging. Here are common approaches.
- Short expiration times: Simplest approach, limits damage window
- Token blacklist: Store revoked jti values in a fast cache (Redis)
- Token versioning: Include a version claim, increment on logout/password change
- Reference tokens: Store tokens server-side, return opaque reference to client
- Refresh token rotation: Issue new refresh token with each use, revoke old ones
Validating JWT claims in code
Always validate claims server-side. Never trust claims without verification.
- Verify signature first, then validate claims
- Check exp is in the future (with clock skew tolerance)
- Check nbf is in the past (if present)
- Validate iss matches expected issuer exactly
- Validate aud includes your service identifier
- Check required custom claims exist and have valid values
Common JWT security mistakes
Avoid these frequently seen JWT implementation errors.
- Storing tokens in localStorage (vulnerable to XSS)
- Not validating the signature before reading claims
- Using weak or predictable signing secrets
- Accepting the alg header without validation
- Setting expiration too far in the future
- Including sensitive data in the payload
- Not implementing token revocation for logout
JWT storage recommendations
Where you store JWTs affects security. Choose based on your application type.
- HttpOnly cookies: Best for web apps, immune to XSS attacks
- Memory only: Most secure for SPAs, lost on page refresh
- Secure cookie + CSRF token: Balance of security and convenience
- Never use localStorage for sensitive tokens
- Mobile apps: Use secure storage APIs (Keychain, Keystore)
Debugging JWT issues
When JWTs fail validation, systematic debugging helps identify the problem.
- Decode the token to inspect claims (use our JWT Decoder tool)
- Check if exp timestamp has passed
- Verify the signing algorithm matches server expectations
- Ensure clock times are synchronized between servers
- Confirm the secret/public key matches between issuer and verifier
- Look for malformed Base64URL encoding
FAQ
What is the difference between registered and private claims?
Registered claims are predefined by the JWT specification (like exp, iss, sub) and have standard meanings. Private claims are custom claims you define for your application (like user_id or role). Registered claims ensure interoperability, while private claims let you include application-specific data.
Should I encrypt my JWT payload?
JWTs are signed, not encrypted by default. Anyone can decode and read the payload. If you need to hide claim values, use JWE (JSON Web Encryption) or avoid putting sensitive data in claims entirely. For most applications, signing alone is sufficient when combined with HTTPS.
How long should JWT tokens be valid?
Access tokens should be short-lived, typically 15-60 minutes. Refresh tokens can be longer (days to weeks) but require secure storage and revocation capability. Shorter expiration times limit the damage if a token is compromised.
What happens if a JWT is stolen?
A stolen JWT can be used by an attacker until it expires. This is why short expiration times are important. Implement token revocation through blacklists or refresh token rotation. Also use secure storage (HttpOnly cookies) to prevent theft through XSS.
Can I change claims in an existing JWT?
No. JWTs are immutable once signed. Any modification to the header or payload invalidates the signature. To change claims, you must issue a new token with the updated values.
Why use sub instead of user_id for the user identifier?
The sub (subject) claim is the registered claim for identifying the principal. Using it ensures interoperability with libraries and services that expect standard claims. You can still use custom claims like user_id alongside sub if needed.
How do I handle JWT expiration gracefully?
Use refresh tokens to obtain new access tokens before expiration. Implement token refresh logic that detects near-expiration and refreshes proactively. Handle 401 responses by attempting refresh before prompting for re-login.
What is the maximum size for JWT claims?
There is no hard limit in the specification, but JWTs are sent with every request (often in headers). Keep the total JWT size under 8KB to avoid issues with header size limits in servers and proxies. Minimize claims to essential data only.