Timestamps in JWT Tokens

JSON Web Tokens (JWTs) use Unix timestamps in seconds for three standard claims that control token validity. Understanding these claims is essential for implementing secure authentication and authorization.

The three timestamp claims:

{
  "iat": 1704067200,    // Issued At: when the token was created
  "nbf": 1704067200,    // Not Before: token is invalid before this time
  "exp": 1704070800     // Expiration: token is invalid after this time
}

All three are seconds since the Unix epoch, as specified in RFC 7519. Using milliseconds here is a common mistake that produces tokens that appear to expire thousands of years in the future.

Validation logic:

function validateJWT(payload) {
  const now = Math.floor(Date.now() / 1000); // current time in seconds

  if (payload.exp && now >= payload.exp) {
    throw new Error("Token expired");
  }

  if (payload.nbf && now < payload.nbf) {
    throw new Error("Token not yet valid");
  }

  // iat is informational, not typically used for validation
}

Clock skew tolerance:

In distributed systems, server clocks are never perfectly synchronized. A token issued by Server A might appear to be from the future when verified by Server B if B's clock is slightly behind. To handle this, most JWT libraries accept a "clock tolerance" or "leeway" parameter, typically 30-60 seconds.

// jose library example
await jwtVerify(token, key, {
  clockTolerance: 60  // allow 60 seconds of clock skew
});

Security best practices:

• Always set an exp claim. Tokens without expiration remain valid forever if compromised.
• Keep access token lifetimes short (5-15 minutes). Use refresh tokens for longer sessions.
• Use nbf for tokens that should only become valid at a specific future time (e.g., a pre-scheduled access grant).
• Never trust the iat claim for security decisions — it is the token issuer's claim and could be fabricated.

Debugging JWTs: When debugging authentication failures, always compare the token's exp to the current server time. The most common issue is expired tokens, followed by clock skew between the issuer and verifier.