JWT Claims Explained

JWT claims are the pieces of data inside a JSON Web Token payload. They can identify the subject, issuer, audience, expiration time, permissions, tenant context, and other token metadata.

Claims are useful, but they are only trustworthy after the token is validated.

Quick answer

A JWT claim is a name-value pair in the token payload. Common registered claims include sub, iss, aud, exp, nbf, iat, and jti.

Backend systems use claims to understand who the token represents, who issued it, who should accept it, when it expires, and what permissions or context may apply.

Do not trust claims just because they are readable. A backend must verify the JWT signature and validate the expected issuer, audience, expiration, and application-specific rules.

A simple JWT payload

A decoded JWT payload might look like this:

{
  "iss": "https://auth.example.com",
  "sub": "user_123",
  "aud": "api://orders",
  "exp": 1790640000,
  "iat": 1790636400,
  "scope": "orders:read orders:write",
  "tenant_id": "acme"
}

The payload is usually base64url-encoded, not encrypted. Anyone who has the token can often decode and read the claims.

That is why JWTs should not store passwords, secrets, payment details, or sensitive personal data.

sub: subject

The sub claim identifies the subject of the token. In user flows, it usually points to the user. In service-to-service flows, it may point to a client or service identity.

Example:

{
  "sub": "user_123"
}

Treat sub as an identifier, not as the complete user profile. The backend may still need to load current user status, account state, or permissions from its own data store.

iss: issuer

The iss claim identifies who issued the token.

Example:

{
  "iss": "https://auth.example.com"
}

Your API should only trust tokens from expected issuers. Accepting any token that looks like a JWT is a serious security bug.

aud: audience

The aud claim identifies who the token is intended for.

Example:

{
  "aud": "api://orders"
}

Audience validation prevents a token minted for one service from being reused against a different service. This matters in multi-service systems and OAuth integrations.

exp, nbf, and iat

Time-based claims define when a token should be accepted.

Claim	Meaning
exp	Expiration time. The token should not be accepted after this time.
nbf	Not before. The token should not be accepted before this time.
iat	Issued at. The time the token was issued.

These values are usually Unix timestamps. Use the Unix Timestamp Converter when debugging exp, nbf, and iat values.

Keep access tokens short-lived. Long-lived access tokens increase the damage window if they leak.

jti: token ID

The jti claim is a unique token identifier.

It can help with:

• Token replay detection.
• Revocation lists.
• Audit trails.
• Idempotency around token processing.

Not every system needs jti, but it is useful when you need to identify a specific token instance.

Scopes, roles, and permissions

Many JWTs include authorization-related claims:

{
  "scope": "orders:read orders:write",
  "roles": ["support_agent"],
  "tenant_id": "acme"
}

These claims can help APIs make authorization decisions, but they are not a complete permission system by themselves.

If a user is removed from a tenant or loses an admin role, an old JWT may still contain stale claims until it expires. For sensitive actions, the backend may need to check current permissions from the database or authorization service.

Read Authorization vs Authentication for the broader permission model.

Custom claims

Custom claims carry application-specific context. Examples include tenant IDs, organization IDs, plan names, feature flags, or device IDs.

Use custom claims carefully:

• Keep names stable.
• Avoid sensitive data.
• Keep token size reasonable.
• Document which services can rely on each claim.
• Prefer IDs over large embedded objects.

A JWT should not become a portable copy of the entire user record.

Common mistakes

The first mistake is decoding without verifying. Decoding only reads the payload. Verification proves the token was signed by a trusted issuer and has not been changed.

The second mistake is skipping audience validation. A valid token for one API may not be valid for another API.

The third mistake is storing secrets in claims. Signed does not mean encrypted.

The fourth mistake is trusting stale role claims for high-risk actions.

The fifth mistake is accepting tokens after expiration because of clock or validation mistakes. Small clock skew tolerance is normal; ignoring expiration is not.

Practical backend checklist

When validating JWT claims, check:

• Signature.
• Issuer.
• Audience.
• Expiration.
• Not-before time when present.
• Required scopes or permissions.
• Tenant or account context.
• Whether the user or client is still active.

Use the JWT Decoder for local inspection, but remember that a decoded token is not automatically trusted.

Related reading

Read JWT vs Session Authentication for architecture tradeoffs and Access Token vs Refresh Token for token lifecycle decisions. Read OAuth Scopes Explained for scope claims, API Authentication Best Practices for token validation, and OAuth 2.0 vs OpenID Connect to understand access tokens and ID tokens. For the full sequence, browse the Authentication Learning Path.

For the broader security sequence, browse the Backend Security Learning Path.