Table of Contents
From single sign-on (SSO) to secure API calls, JSON Web Tokens (JWTs) are everywhere in modern user authentication. Their appeal lies in being lightweight, portable, and easy to validate across distributed systems. But JWTs are more than just compact strings passed between services. What gives them meaning are the claims they carry—the data points that allow applications to decide whether to grant access, request more proof, or end a session. When used thoughtfully, claims streamline identity and access management (IAM); when overlooked, they can create serious gaps in security.
In this guide, we’ll break down the different types of JWT claims, why they matter, and best practices for keeping them secure.
Main points
JWT claims are the data points inside a token that communicate identity and authorization details.
Claims fall into three categories: registered, public, and private, each serving different purposes.
Applications rely on claims in the payload to validate tokens and make access decisions.
Following best practices and avoiding common pitfalls keeps JWT claims secure and efficient.
What are JWT claims?
A JWT claim is a piece of information expressed as a JSON key–value pair inside a JWT. Claims are how JWTs communicate facts about a subject, such as who the user is, when the token was issued, and how long it remains valid.
Structurally, claims make up the payload of a JWT, which sits between the header and the signature. The header defines metadata about the token, the signature verifies integrity, and the claims provide the actual content that applications rely on to make decisions. For example, a claim might pair a category identifier like "name" with a value such as "Jane Doe". This pairing gives systems context they can use to validate identity, enforce permissions, or share information across trusted services.
In short, claims are what transform a JWT from a random string into meaningful, verifiable data.
The three types of JWT claims
JWT claims fall into three categories: registered claims, public claims, and private claims. Each category serves a different purpose, but all follow the same key–value format that makes claims simple to parse and validate across systems.
Registered claims
Registered claims are defined in the IETF JWT standard (RFC 7519). They aren’t mandatory but are widely recommended to promote interoperability. These claims are conventionally abbreviated to three letters for compactness. Common examples include:
iss (issuer): Identifies the party that issued the JWT
sub (subject): Identifies the subject of the JWT
aud (audience): Identifies the intended recipients
exp (expiration time): Defines when the JWT expires
nbf (not before): Defines when the JWT becomes valid
iat (issued at): Defines the time the JWT was issued
jti (JWT ID): Provides a unique identifier for the token
Public claims
Public claims are not part of the core JWT standard but are registered with the IANA JWT Claims Registry to avoid naming collisions. They often originate from related standards like OpenID Connect (OIDC) and include fields such as:
name: A full name for the subject
given_name / family_name / preferred_username: More specific identifiers
profile / picture / website: URLs pointing to user-related resources
phone_number: A preferred phone number, optionally with verification status
These claims expand JWTs’ utility for identity-related use cases without requiring custom development.
Private claims
Private (or custom) claims are created for use between specific parties and are not included in the IANA registry. They’re useful when applications need to convey proprietary or context-specific information, such as a customer account ID or an internal role designation.
Private claims can make JWTs more flexible but also carry risk. Because they’re not standardized, both parties must agree on their meaning and validation. Misuse or inconsistent validation can introduce vulnerabilities, so careful design and testing are key.
How JWT claims work in identity and access management
JWTs are widely used in IAM because claims provide a compact, verifiable way to share identity data across systems. When a user signs in, the identity provider issues a JWT that contains claims describing who the user is, how their identity was verified, and what they are allowed to access.
Applications and APIs then validate these claims by checking values such as issuer (iss), audience (aud), and expiration (exp). This validation ensures the token was issued by a trusted source, is intended for the current application, and is still valid. Based on the claims, the application can decide whether to grant access, request additional authentication, or deny the request.
Typical IAM workflows that rely on JWT claims include SSO and identity federation, where multiple applications or services need to share authentication and authorization data seamlessly.
Security best practices for JWT claims
While JWT claims streamline communication between systems, they can also introduce risks if implemented carelessly. To keep tokens secure and compliant, it’s critical to follow best practices:
Validate all claims: Always check iss, aud, exp, and other relevant fields against expected values. Skipping validation opens the door to replay or injection attacks.
Avoid storing sensitive data in claims: Even signed tokens can be decoded, so never place passwords, secrets, or personally identifiable information in a payload.
Use short lifespans with refresh tokens: Keep JWTs valid only as long as necessary to reduce exposure if compromised.
Enforce expiration and “not before” checks: Expiration (exp) and “not before” (nbf) claims must be respected to prevent replay attacks.
Sign and verify with strong algorithms: Algorithms like RS256 or ES256 provide stronger guarantees than weaker options such as HS256 with poor key management.
Even with these practices in place, teams often stumble on recurring mistakes:
Ignoring expiration checks: Accepting expired tokens opens the door to replay attacks.
Predictable jti values: Token IDs should be random and unique; sequential IDs can be exploited.
Overloading JWTs with unnecessary data: Extra claims bloat tokens and may leak details if intercepted.
Misusing private claims: Without clear definitions and validation, private claims can break workflows or create vulnerabilities.
JWTs are powerful tools, but they only remain secure when claims are validated and enforced consistently. Integrating them into a trusted authentication and authorization solution makes it easier to apply these practices reliably.
JWT claims done right with Descope
JWT claims are the backbone of how tokens communicate identity and authorization data. By understanding their types, validating them properly, and avoiding common mistakes, organizations can strengthen their authentication flows and reduce security gaps.
Descope makes it easier to implement JWT-based authentication and authorization without building everything from scratch. With drag & drop workflows and built-in claim validation, you can secure logins and API access in just a few lines of code.
Sign up for a Free Forever account to start experimenting with JWT claims today, or book time with our team to learn how Descope can streamline your customer identity and access management.
