clerk-clock-skew-jwt

Clerk JWT and Clock Skew

Overview

Clerk session tokens and custom JWT templates are signed JSON Web Tokens. The verifier always checks three time-based claims:

Claim	Meaning	Failure error
iat (issued at)	When the token was minted	(rare) invalid-iat or iat must be in the past
nbf (not before)	Earliest moment the token is valid	token-not-active-yet (Clerk error reason)
exp (expiration)	Latest moment the token is valid	token-expired (Clerk error reason)

Clock skew occurs when the verifier's wall clock is offset from the issuer's wall clock. If the verifier is behind, even freshly minted tokens fail nbf. If the verifier is ahead, long-lived tokens can fail exp early. Both directions break auth.

Clerk's own backend SDK applies a small tolerance (clockSkewInMs default 5000 ms) and the Dashboard exposes a session-level "Allowed Clock Skew" / nbf offset setting for JWT templates. Third-party libraries used to verify Clerk-issued JWTs have their own leeway settings; the safe defaults differ by library.

Time Claims in Clerk Tokens

A decoded Clerk session token typically contains numeric epoch-second values for iat, nbf, and exp. Decode the JWT (without verification) at a tool like jwt.io to inspect them when diagnosing failures.

The verifier must check nbf <= now + leeway and exp >= now - leeway. A token that is "active" must satisfy both bounds. If nbf > now even by one second, the token is rejected with token-not-active-yet. If exp < now, the token is rejected with token-expired.

iat is informational; most libraries do not require it. Clerk's tokens do include iat, and some libraries (for example golang-jwt/jwt v5) require WithIssuedAt() to enable iat validation.

Clerk SDK Clock Skew Configuration

Clerk's verifyToken() (in @clerk/backend, @clerk/nextjs/server, and equivalent) accepts a clockSkewInMs option. Documented default: 5000 (5 seconds). The same option is exposed to authenticateRequest for HTTP requests.