JWT Claims Reference Guide | ToolBoxes

JWT claims are the key-value pairs that carry information inside a token. Some claims are standardized by the IETF and have defined semantics. Others are registered with IANA for interoperability. The rest are custom claims defined by your application. Knowing which claims to use—and how—helps you build tokens that are secure, interoperable, and easy to debug.

Registered Claims

These seven claims are defined in RFC 7519. All have three-letter keys to keep tokens compact.

Claim	Name	Purpose	Example
`iss`	Issuer	Identifies the principal that issued the token	`auth.example.com`
`sub`	Subject	Identifies the principal that is the subject of the token	`user-42`
`aud`	Audience	Identifies the recipients the token is intended for	`api.example.com`
`exp`	Expiration	NumericDate after which the token must not be accepted	`1716940800`
`nbf`	Not Before	NumericDate before which the token must not be accepted	`1716937200`
`iat`	Issued At	NumericDate at which the token was issued	`1716937200`
`jti`	JWT ID	Unique identifier for the token (for revocation)	`a1b2c3d4-e5f6-7890`

How Each Is Used

iss (Issuer): The iss claim lets consumers verify that the token came from a trusted authority. When validating, compare the iss value against a list of trusted issuers. This prevents token confusion attacks where a token issued by one service is accepted by another.

sub (Subject): The sub claim identifies the user or entity the token represents. It should be a unique, stable identifier—ideally a UUID rather than an email address, which can change. The sub claim must be unique within the scope of the issuer.

aud (Audience): The aud claim specifies which services should accept the token. A token with aud: "api.example.com" should be rejected by analytics.example.com. Always validate aud on the consuming side to prevent cross-service token reuse.

exp (Expiration): The exp claim is the most critical security constraint. Tokens without exp never expire, creating indefinite attack windows. Always set exp and always validate it. Allow 30–60 seconds of clock skew tolerance.

nbf (Not Before): The nbf claim prevents tokens from being used before a specific time. Useful for scheduled token activation or tokens issued in advance for future use.

iat (Issued At): The iat claim enables age-based policies. For example, reject access tokens older than 15 minutes regardless of exp, or force re-authentication for sensitive operations if iat is more than 5 minutes ago.

jti (JWT ID): The jti claim provides a unique token identifier. Use it for token revocation—store the jti of revoked tokens in a blocklist, or track issued jti values to detect token reuse.

Public Claims

Public claims are registered with IANA to avoid naming collisions between different systems. You can view the full registry at the IANA JWT Claims Registry. Commonly used public claims include:

Claim	Purpose
`name`	Full name of the subject
`email`	Email address
`role`	Application role
`scope`	Space-separated list of scopes (OAuth 2.0)
`azp`	Authorized party—the client the token was issued to
`nonce`	Value to associate the token with a specific request (OIDC)
`auth_time`	Time when the user authenticated
`acr`	Authentication Context Class Reference
`amr`	Authentication Methods References
`at_hash`	Access token hash (for ID tokens)
`c_hash`	Authorization code hash (for ID tokens)

The scope and azp claims are particularly important in OAuth 2.0 / OpenID Connect flows. The scope claim defines what the token holder can do, while azp identifies which client application requested the token.

Private Claims

Private claims are custom key-value pairs defined by your application. They carry domain-specific data but risk naming collisions if two applications use the same key for different purposes.

{
  "sub": "user-42",
  "role": "admin",
  "tenant_id": "acme-corp",
  "permissions": ["read:reports", "write:reports", "delete:users"],
  "department": "engineering",
  "session_id": "s_abc123"
}

Best practices for private claims:

Use namespaces or prefixes to avoid collisions: myapp:tenant_id instead of tenant_id
Keep the payload small—every byte increases the token size and HTTP header overhead
Never put sensitive data (passwords, API keys) in claims—JWT payloads are base64-encoded, not encrypted
Validate private claims on the server side—never trust claims enforcement to the client

Claims Validation Checklist

When implementing JWT validation, verify these claims in order:

Signature — Verify the token's signature using the correct algorithm and key
iss — Match against your trusted issuer list
aud — Match against your service's expected audience
exp — Reject tokens past their expiration (with clock tolerance)
nbf — Reject tokens used before their activation time
jti — Check the blocklist for revoked tokens
Private claims — Validate application-specific claims (role, permissions, tenant)

Skipping any step weakens your security. The signature check prevents tampering, while claim validation prevents misuse of valid tokens in unintended contexts.

For visual inspection of JWT claims, the JWT Decoder tool parses tokens and displays all registered, public, and private claims in a structured format.