Guide Updated

JWT nbf Claim (Not Before)

The JWT nbf (not before) claim is a Unix timestamp before which the token must not be accepted. Learn when to use nbf, when to omit it, and how to validate it with clock skew leeway.

The `nbf` (not before) claim is a Unix timestamp (seconds since epoch) before which the token must not be accepted. The token is valid only inside the window `nbf ≤ now < exp`. It is defined in RFC 7519 §4.1.5 and is the mirror image of `exp`.

Format and values

A numeric Unix timestamp in seconds, identical in type to `exp`. Example: `"nbf": 1750087200`.

Validation rule

Enforce `nbf` when present with the same clock-skew tolerance as `exp` (30–60 seconds). Never skip `nbf` validation on the assumption that your system does not use it: an attacker or a misconfigured issuer may include it. If `nbf` is in the future, reject the token (subject to your leeway window).

Common mistakes

  • Skipping nbf validation because 'we don't use nbf'. If a token carries nbf, enforce it; otherwise an attacker could craft tokens with a future nbf that your verifier incorrectly accepts now.
  • Setting nbf equal to exp. That makes the validity window empty: the token can never be valid. The claims.mdx guide's example payload has nbf = iat and exp 60 minutes later, which is correct.
  • Applying leeway to nbf but not exp, or vice versa. Use the same leeway for both.

Code examples

Validate nbf (Node.js: jsonwebtoken)

Validate nbf (Node.js: jsonwebtoken) 
jwt.verify(token, secret, {
  algorithms: ["HS256"],
  clockTolerance: 60,   // applies to both exp and nbf
});

Issue a token valid in the future (Python: PyJWT)

Issue a token valid in the future (Python: PyJWT) 
import datetime
token = jwt.encode(
    {
        "sub": "user_123",
        "nbf": datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(minutes=5),
        "exp": datetime.datetime.now(tz=datetime.timezone.utc) + datetime.timedelta(hours=1),
    },
    secret,
    algorithm="HS256",
)

Frequently asked questions

  • What is the nbf claim in a JWT?

    nbf (not before) is an RFC 7519 registered claim: a Unix timestamp in seconds before which the token must not be accepted. The token is valid only in the window nbf ≤ now < exp. Use nbf when you need to pre-issue tokens that become valid at a future time (scheduled releases, pre-deployment emails). For standard auth tokens, omit nbf and rely on exp alone.

  • When should I use the JWT nbf claim?

    Use nbf when you pre-issue tokens that should not be valid immediately: download links for scheduled releases, tokens embedded in emails sent before a deployment, or staggered access rollouts. For standard authentication tokens, nbf adds operational complexity without benefit: if you do not need future-activation tokens, omit nbf and rely on exp alone.

  • Should I apply clock skew leeway to nbf?

    Yes: apply the same 30 to 60 second leeway you apply to exp. A token issued by a server running 30 seconds fast would otherwise appear not-yet-valid on a verifier running on time. Apply leeway to exp and nbf together; never apply it to iat (a future iat is suspicious, not a clock-sync issue).

Related