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.