JWT claims are the key-value pairs inside a JSON Web Token's payload that say who the token is about, who issued it, who it's for, when it expires and what the holder is allowed to do. Some claims are standardized, like iss (issuer), sub (subject), aud (audience) and exp (expiration), and others are custom, like a user's roles or tenant ID. An API should trust a claim only after it has verified the token's signature and checked the standard claims.
What are JWT claims?
A JWT has three parts separated by dots: a header, a payload and a signature. The payload is a JSON object, and each property in it is a claim:
{
"iss": "https://auth.example.com",
"sub": "8f14e45f-ceea-467a-9575-0f1a2b3c4d5e",
"aud": "https://api.example.com",
"exp": 1794787200,
"iat": 1794783600,
"scope": "invoices:read",
"tenantId": "acme"
}Claims aren't secret. In a signed JWT, which is the most common kind, the payload is only Base64url-encoded, so anyone holding the token can read it. The signature stops claims from being changed, not from being read. Don't put passwords, secrets or sensitive personal data in claims unless the token is also encrypted.
The three types of JWT claims
RFC 7519, the JWT standard, defines three kinds of claim names:
- Registered claims: seven short names defined by the standard itself, such as
iss,subandexp. None is required by RFC 7519, but other standards and most APIs require several. - Public claims: names registered in the IANA "JSON Web Token Claims" registry (for example the OpenID Connect claims below) or names made collision-resistant, such as a URL you control (
https://example.com/claims/plan). - Private claims: names agreed between the token issuer and the API that uses it, such as
tenantIdorroles. They aren't registered, so pick names that won't clash with registered ones.
Registered JWT claims
| Claim | Name | What it holds | What the API should check |
|---|---|---|---|
iss | Issuer | Who issued the token, usually the authorization server's URL | It exactly matches the issuer you trust |
sub | Subject | Who or what the token is about, such as a user ID or a client ID | Use it as the identity; don't assume it's an email |
aud | Audience | Who the token is for: one string or an array, usually your API's identifier | Your API's identifier is in it; reject tokens meant for other APIs |
exp | Expiration time | Time after which the token must not be accepted (seconds since 1970, UTC) | Current time is before it, allowing a small clock skew |
nbf | Not before | Time before which the token must not be accepted | Current time is after it, if present |
iat | Issued at | When the token was issued | Optional sanity check, for example reject tokens issued in the future |
jti | JWT ID | A unique ID for this token | Use it to detect replay or to revoke a specific token, if you track IDs |
OpenID Connect and access-token claims
Two other standards build on JWTs and add claims you'll see often.
ID tokens (OpenID Connect). An ID token tells your app who signed in. Besides iss, sub, aud, exp and iat, OpenID Connect Core defines:
| Claim | What it holds |
|---|---|
auth_time | When the user actually authenticated |
nonce | A value your app sent in the sign-in request, to prevent replay |
acr | Authentication context class: how strong the sign-in was |
amr | Authentication methods used, such as password or MFA |
azp | Authorized party: the client the token was issued to |
name, email, email_verified and other profile claims | Standard user profile information |
JWT access tokens. When an authorization server issues access tokens as JWTs, RFC 9068 defines a standard profile: the header's typ is at+jwt, and the payload includes iss, exp, aud, sub, client_id, iat and jti, plus optional scope, roles, groups and entitlements. In token exchange (on-behalf-of) flows, RFC 8693 adds act, which names the party acting on the subject's behalf.
Don't use an ID token to call your API. ID tokens are for the client app; access tokens are for APIs.
Custom claims
Custom (private) claims carry what your application needs to make decisions without another lookup, such as:
- the user's tenant or organization ID
- roles and permissions
- plan or feature entitlements
- a session ID
Keep them small. Every claim is sent with every request, HTTP headers are usually limited to roughly 8–16 KB, and long lists of permissions or features can push tokens over that. Put stable, frequently checked facts in claims and look up the rest.
Treat custom claims as a snapshot from when the token was issued. If a user's role changes, the old token still carries the old role until it expires, which is one reason to keep access tokens short-lived.
Which claims should your API validate?
Validate in this order, and reject the token if any check fails:
- Signature, using the issuer's public key and only the algorithms you expect (for example RS256). Never accept
alg: none. issmatches your trusted issuer.audincludes your API.expandnbfare valid for the current time, with a small clock skew allowance.typ, if your issuer sets it, matches what you expect (such asat+jwt), so an ID token can't be passed off as an access token.- Your custom claims, such as the tenant ID and permissions needed for this request.
RFC 8725, the JWT best current practices, explains why each check matters.
In Node.js, the jose library does steps 1–4 in one call:
import { createRemoteJWKSet, jwtVerify } from 'jose';
const jwks = createRemoteJWKSet(
new URL('https://auth.example.com/.well-known/jwks.json')
);
export async function verifyAccessToken(token) {
const { payload } = await jwtVerify(token, jwks, {
issuer: 'https://auth.example.com',
audience: 'https://api.example.com',
algorithms: ['RS256'],
clockTolerance: 30,
});
return payload; // now check tenantId, roles or scope for this request
}Where JWKS fits in
A JSON Web Key Set (JWKS, RFC 7517) is a JSON document listing the public keys an issuer uses to sign tokens. Each JWT's header has a kid (key ID), and your API picks the matching key from the issuer's JWKS URL to check the signature. Because the API fetches keys by ID, the issuer can rotate keys without breaking validation. Cache the key set, and refetch it when you see a kid you don't recognize.
JWT claims with Frontegg
Frontegg is customer identity and access management (CIAM) for B2B SaaS. Its access tokens are JWTs. Frontegg recommends signing them with RS256, and you can validate them in any backend with your environment's JWKS endpoint or with Frontegg's middleware.
With JWT token templates, you choose which claims each token carries:
| Group | Claims |
|---|---|
| Required OpenID Connect claims (can't be removed) | iss, sub, aud, exp, iat |
| Required Frontegg claims | type, tenantId |
| User | name, username, email, emails, email_verified, phoneNumber, metadata, profilePictureUrl, externalId, groups |
| Entitlements | roles, permissions, planIds, featureKeys |
| Account | tenantIds (all of the user's tenants) |
| Session | sid, applicationId |
You can also add custom claims built from template variables, such as values from user metadata, and claims added by a JWT-generation prehook take precedence over the template. roles, permissions, groups, planIds and featureKeys are always arrays. Frontegg's backend SDKs use roles and permissions for access checks, so keep them in templates you use with the SDKs.
Custom roles, permissions and feature flags are part of Frontegg's Enterprise plan; see Frontegg pricing.
FAQ
What are claims in a JWT?
Claims are the key-value pairs in a JWT's payload. They describe the token's subject, issuer, audience and lifetime, and can carry application data such as roles or a tenant ID.
What are the registered JWT claims?
RFC 7519 defines seven: iss (issuer), sub (subject), aud (audience), exp (expiration time), nbf (not before), iat (issued at) and jti (JWT ID). None is mandatory in RFC 7519 itself, but most APIs require iss, sub, aud and exp.
What is the aud claim in a JWT?
aud (audience) names who the token is meant for, usually your API's identifier. An API should reject any token whose audience doesn't include it, so a token issued for one API can't be used against another.
What is the azp claim?
azp (authorized party) is an OpenID Connect claim that names the client the token was issued to. It matters when a token's audience includes more than one party.
Are JWT claims encrypted?
Not usually. Most JWTs are signed, not encrypted, so anyone with the token can decode and read the claims. Don't put secrets or sensitive personal data in claims unless you use an encrypted JWT (JWE).
How do I add custom claims to a JWT?
Add them where tokens are issued: in your authorization server or identity provider's token configuration, or in code that runs before the token is signed. Use names that won't collide with registered claims, keep them small, and validate them in your API like any other input.
Put this into practice with Frontegg
Frontegg is customer identity and access management (CIAM) for B2B SaaS. It's free up to 7,500 monthly active users, including 5 SSO/SCIM connections.
Start for free