JWT nbf (Not Before) Claim

The nbf (not before) claim specifies the earliest time at which a JWT should be accepted for processing. If a server receives a token and the current time is before the nbf value, the token must be rejected. Like exp and iat, the value is expressed as seconds since the Unix epoch.

How nbf works:

{
  "sub": "user789",
  "iat": 1700000000,
  "nbf": 1700003600,
  "exp": 1700007200
}

In this example, the token is issued at timestamp 1700000000 but cannot be used until 1700003600 (one hour later). It then remains valid until 1700007200. This creates a deferred activation window where the token exists but is not yet usable.

Practical use cases for nbf:

The most common scenario is pre-issuing tokens for scheduled operations. For example, a CI/CD system might generate deployment tokens hours before a scheduled release, with nbf set to the deployment window start time. Another use case is batch token generation: an admin portal might create tokens for multiple users in advance, each with different nbf values corresponding to their access start dates.

Clock skew handling:

Real-world distributed systems rarely have perfectly synchronized clocks. JWT libraries typically accept a configurable clock skew tolerance (often called clockTolerance or leeway). A common setting is 30-60 seconds. This means a token with nbf set to 12:00:00 might be accepted at 11:59:30 if the leeway is 30 seconds. Without this tolerance, legitimate tokens could be rejected simply because one server's clock is slightly behind.

Security relevance:

The nbf claim is less commonly used than exp but is valuable in scenarios requiring precise control over token validity windows. When combined with exp, it creates an exact validity range. Libraries that validate nbf prevent attackers from using pre-issued tokens before their intended activation time. Always ensure your JWT validation logic checks nbf when present; ignoring it defeats its purpose.