JWT Claims Reference
JWT claims describe the subject, issuer, intended audience, time bounds, and application data in a token. Treat decoded claims as untrusted until the signature and every required validation rule pass.
Registered claim names
| Claim | Name | Validation role |
|---|---|---|
| iss | Issuer | Identifies the principal that issued the token. |
| sub | Subject | Identifies the principal that is the token subject. |
| aud | Audience | Identifies the intended recipients. |
| exp | Expiration Time | The token must not be accepted on or after this time. |
| nbf | Not Before | The token must not be accepted before this time. |
| iat | Issued At | Records when the token was issued. |
| jti | JWT ID | Provides a unique token identifier under the issuer's rules. |
Issuer and subject
Validate iss against an exact configured issuer and use that issuer's discovery metadata and keys. Similar domains, tenants, and environments are not interchangeable. Interpret sub only within the issuer's namespace. Do not assume it is an email address, username, or stable identifier across different clients unless the provider contract says so.
Audience
aud can be one case-sensitive string or an array. An API should require its documented identifier to be present. A token from a trusted issuer but intended for another API is not valid for the current service. Avoid substring matching or disabling audience validation. ID tokens commonly name the client application and are not general-purpose API access tokens.
Time claims
exp, nbf, and iat use NumericDate values measured in seconds from the Unix epoch. Keep verifier clocks synchronized and allow only a small documented skew. Reject expired tokens and tokens that are not yet active. An unusually old issued-at time can inform policy, but the application must define any maximum token age explicitly.
JWT ID and replay
jti can support revocation, one-time operations, or replay detection when the issuer guarantees suitable uniqueness and the verifier maintains state. Its presence alone does not stop replay. Retain denylist or consumed-token state only for the required lifetime and scope it by issuer to avoid collisions.
Custom authorization claims
Scopes, roles, permissions, tenant IDs, and token-type claims are issuer-specific. Validate their exact type and semantics. Do not treat an arbitrary claim name as authoritative merely because it appears in a signed token; the issuer, client, grant, and audience configuration determine what it means. Apply least privilege and enforce resource ownership separately.
Header fields are not claims
alg, kid, and typ normally appear in the JOSE header. Configure an algorithm allowlist rather than trusting alg from the token. Use kid only to select among trusted issuer keys. Enforce the expected token type according to the authorization profile.
Validation order
Parse within size and structure limits, select a trusted key, verify the approved signature algorithm, then validate issuer, audience, time, token type, and required authorization claims. Fail closed without exposing token contents in logs. Inspect safe examples locally with the JWT Decoder.
Frequently Asked Questions
Does decode verify a JWT?
No. Verify signature and claims separately.
Is exp in milliseconds?
No. NumericDate uses Unix seconds.
Can aud be an array?
Yes. Require the intended audience to be present.