nbf (Not Before) Claim in a JWT
nbf is the time before which the token must not be accepted. It is the opposite bound to exp and is normally either absent or equal to the issue time, so a non trivial nbf is worth a second look.
At a glance
- Claim
- nbf (Not Before)
- Defined in
- RFC 7519 section 4.1.5
- Value type
- NumericDate: seconds since 1970-01-01T00:00:00Z
- Required
- Optional everywhere. OpenID Connect ID tokens do not define it and rarely carry it.
- Typical value
- Equal to iat, or a scheduled activation time in the future
- In the decoder
- Explained by name as Not Before, rendered as local time, and flagged as a warning when it is still in the future.
In detail
nbf uses the same NumericDate encoding as exp and iat and defines the front edge of the validity window. A verifier processing a token before that instant must reject it. The same small leeway RFC 7519 allows for exp applies here, and it matters more, because a verifier whose clock is a second behind the issuer will reject brand new tokens if nbf equals iat and the leeway is zero.
Most tokens either omit nbf or set it to the issue time, where it adds nothing. It earns its place when issuance and activation are deliberately separated: a licence that starts on renewal day, an invitation that opens at a published time, a signed pre-authorization handed out in advance of a maintenance window. In those cases nbf is doing real work that exp cannot do.
It is not a security control against replay or theft. Anyone holding the token simply waits. What it does provide is an issuer side statement of intent that every conforming verifier enforces without extra code, which is more reliable than scattering a start date check through the services that consume the token.
The decoder shows nbf under Registered claims with the label Not Before and converts it to a readable local timestamp next to the raw number. When the value is in the future the validation list raises a warning saying the token is not yet valid, which is the quickest way to explain an API that is rejecting a token that looks otherwise perfect.
Examples
{
"iat": 1735689600,
"nbf": 1738368000,
"exp": 1740787200,
"sub": "5f8d0c1e-9a2b-4c3d-8e7f-1a2b3c4d5e6f"
}Issued 2025-01-01, unusable until 2025-02-01, dead after 2025-03-01.
Things that catch people out
- Setting nbf exactly equal to iat and allowing no leeway. Any verifier whose clock trails the issuer rejects tokens for the first second or two of their life.
- Confusing nbf with iat. iat records when the token was made and never blocks anything; nbf is the one that makes a verifier refuse the token.
- Assuming every consumer enforces it. Some minimal verifiers check the signature and exp only, so nbf on its own is not a safe way to gate access.
Try it: JWT Decoder
Paste a token to decode the header and payload, read the claims and expiry, and verify the signature in your browser. Nothing is uploaded.
JWT Decoder
LOCAL · Browser-OnlyDecode and inspect JSON Web Tokens without sending them to a server
Related JWT claims and algorithms
All jwt claims and algorithms →exp (Expiration Time) Claim in a JWT
The exp claim sets when a JWT stops being accepted. NumericDate format, clock skew allowances, and the four expiry states the decoder shows.
iat (Issued At) Claim in a JWT
The iat claim records when a JWT was created. What it is good for, why it is not an expiry, and the age and lifetime figures the decoder derives.
auth_time Claim in an OpenID Connect ID Token
The auth_time claim records when the end user actually authenticated, not when the token was issued. How max_age uses it and how the decoder shows it.
jti (JWT ID) Claim in a JWT
The jti claim gives a JWT a unique identifier. How it supports replay detection and denylists, what it costs to store, and how the decoder shows it.
azp (Authorized Party) Claim in a JWT
The azp claim names the client an ID token was issued to. When OpenID Connect requires it, how it differs from aud, and what the decoder shows.
nonce Claim in an OpenID Connect ID Token
The nonce claim binds an ID token to one authentication request. How the value round trips, why it must be compared, and how the decoder shows it.
Tools for this
- JWT Decoder Free online JWT decoder - decode and inspect JSON Web Tokens without sending them to a server
- Timestamp Converter Free online timestamp converter - convert between Unix timestamps and human-readable dates instantly