JWT Clock Skew
Clock skew is the time difference between the issuing authentication server and verifying API servers. JWT libraries often allow a small leeway when checking exp and nbf so minor NTP drift does not reject otherwise valid tokens during normal operations. Typical leeway is tens of seconds, not many minutes. Excessive leeway weakens expiry guarantees and widens replay windows for stolen tokens. Prefer synchronized clocks via NTP or chrony and keep leeway minimal and consistent. When debugging invalid token errors, compare iat and exp timestamps to verifier UTC time before changing secrets or algorithms. Document leeway settings across services so microservices behave consistently under the same policy.
Why It Matters
Undiagnosed skew causes flaky 401 responses that teams mistakenly blame on wrong keys or broken deploys. Over-correcting with huge leeway creates lasting security debt that is hard to unwind. Treat time synchronization as part of authentication reliability engineering and keep cryptographic claim checks appropriately strict in every environment. Sync clocks with NTP on every issuer and verifier, keep claim leeway small (often tens of seconds), and investigate regional 401 spikes as time problems before blaming keys. Document the exact leeway your shared verify helper uses.
Code Example
jwt.verify(token, secret, { algorithms: ['HS256'], clockTolerance: 30 });Related Terms
Related Tools
Related Articles
Frequently Asked Questions
What leeway is reasonable for APIs?
Often 30–60 seconds for well-synced fleets. Larger windows hide real clock bugs and widen replay windows; fix NTP instead of raising leeway indefinitely.
Does clock skew affect HMAC signatures?
HMAC integrity itself is not time-based, but exp/nbf/iat claim checks are. Skew shows up as intermittent claim failures even when the signature bytes are valid.
Why do tokens fail only on some nodes?
Those nodes are often out of sync. Compare system time across issuers and verifiers, then normalize NTP before changing secrets or algorithms.