JWT exp and nbf Clock-Skew Policy for LLM APIs
A JWT clock-skew policy should define one small, measured leeway for exp and nbf validation at the LLM API verifier, apply it consistently across replicas, and preserve the raw claim values and effective acceptance boundaries in protected evidence. This guide turns that policy into boundary tests for authenticated user and agent requests.

A JWT reaches an LLM API verifier at 14:00:03 UTC with exp set to 14:00:00. The verifier has a configured three-second leeway, so the token remains inside its effective acceptance boundary for that instant. Four seconds later, the same token must fail expiration validation before its prompt reaches model policy or a provider adapter.
That decision needs one clock source, one documented leeway, and boundary evidence from every production replica. A library default hidden in application code is an undocumented extension of token lifetime. The release gate should make the extension visible.
TL;DR
- Define one small, measured leeway for
expandnbf; never inherit an unknown library default. - Apply the allowance symmetrically and consistently across every verifier replica, using synchronized UTC clocks.
- Test the exact second before, at, and after each effective boundary. Record the verifier clock, raw claim, configured leeway, and reason.
- Keep
iat, maximum token age, replay state, and route authorization as separate checks with explicit policies.
exp and nbf create two acceptance boundaries
Section 4.1.4 of RFC 7519 says a JWT must be rejected on or after its expiration time. The current time has to remain before exp. Section 4.1.5 gives nbf the opposite boundary: the current time has to be at or after the not-before value before processing may begin. Both claims use NumericDate values measured in seconds since the Unix epoch.
The RFC permits a small implementation leeway, usually no more than a few minutes, to account for clock skew. That permission leaves the deployment to choose and document a value. It provides no universal five-minute default and no instruction to stretch a token until downstream dependencies recover.
For a configured leeway L, a practical verifier expresses two effective boundaries. Expiration remains acceptable only while verifier time is earlier than exp + L. Not-before becomes acceptable once verifier time reaches nbf - L. Write those expressions in the token-profile contract. A reviewer should be able to calculate the result with the claim values and the verifier timestamp printed on one sheet of paper.
Leeway is a security parameter
Every second of expiration leeway extends the interval in which a stolen bearer token may be accepted. Every second applied to nbf permits use before the issuer's stated start time. The right value comes from measured clock behavior and the token profile's risk, rather than a round number copied from a framework example.
Start with the actual production time path. Identify the clock synchronization service, alert threshold, virtual-machine or container host behavior, and the maximum observed offset during failover. Include the authorization server and each resource-server verifier. A three-second offset between two gateway pods can produce different decisions for the same request at the same load balancer.
My blunt view is that a five-minute default is a credential-lifetime change disguised as tolerance.
Set the smallest allowance supported by measured offsets and operational recovery. Keep the value in versioned verifier configuration associated with issuer, token type, and resource audience. If one token profile needs a different value, give that profile a separate policy identifier. Silent per-route exceptions make incident reconstruction guesswork.
The AI gateway fail-closed guide covers the wider dependency rule. Clock synchronization alarms should produce a defined verifier state. A host whose offset exceeds the approved bound should leave the serving pool or reject tokens under the documented failure policy.
Validation order protects the LLM route
Time claims belong inside the complete JWT validation profile. RFC 7519 Section 7.2 requires rejection when a validation step fails. RFC 8725 Section 3.1 requires the verifier to enforce a caller-configured algorithm set and match the declared algorithm to the cryptographic operation.
Bound token size and parse the JOSE structure first. Select the trusted issuer profile and permitted algorithm, then verify the signature with issuer-bound key material. Validate token type, issuer, audience, required claims, nbf, and exp. Only a fully validated identity should reach tenant, model, region, tool, and data-class authorization.
This order keeps forged claim values away from policy. It also avoids logging an attacker-controlled expiration value as if it described an authenticated principal. The LLM JWT issuer validation guide owns the issuer and key binding. This guide owns the time-boundary policy and evidence.
Apply leeway once at the component that authenticates the LLM resource request. A proxy, application server, and provider adapter should never each add their own allowance to the same inbound token. That authentication component produces the authoritative time result, which downstream policy consumes with the resolved identity context.
iat and maximum age need their own rule
Section 4.1.6 of RFC 7519 defines iat as the time at which the JWT was issued. The claim can support an age calculation, while the base JWT specification leaves its use optional. Treat it as an issuance fact. If the token profile requires a maximum age or rejects future issuance times, state that separate rule explicitly.
For example, a profile may require iat, reject a value too far in the future under the same measured clock allowance, and impose a maximum accepted age even when exp remains later. That age limit is local profile policy. Label its rejection reason separately from exp and nbf failures.
Replay protection remains another control. A token inside its time window can still be a replay. The JWT jti replay-cache guide explains atomic first-use evidence for profiles that promise single use. A clock allowance can influence the replay-record retention horizon, but it never replaces an atomic replay decision.
Keep request deadlines separate too. An accepted token at ingress might expire while a long model response streams. Decide whether authorization is evaluated at request admission, periodically during a stream, or before a privileged follow-on action. Document that semantic choice instead of treating exp as a generic request timeout.
Boundary tests should use controlled time
A useful acceptance fixture freezes the verifier clock or injects a test clock into the validation component. Wall-clock sleeps make the suite slow and create flaky results around scheduler delays. Run the same fixture against the deployed build as well, using short-lived test tokens and synchronized observation.
For exp = T and leeway L, capture these cases:
- At
T - 1, the token passes the expiration check. - At
T, the base RFC boundary has arrived, while configured leeway determines the local result. - At
T + L - 1, the token remains inside the effective local boundary when whole-second NumericDate arithmetic is used. - At
T + L, the token receives the documented expiration rejection. - Far beyond
T + L, it receives the same stable public result without reaching route policy.
For nbf = T, mirror the useful edges around T - L and T. Include a token carrying both time boundaries. Test optional-claim absence under a permissive profile, then remove a required value under a stricter profile and supply a non-numeric value. Exercise fractional parser input according to the library and profile contract rather than assuming all implementations round identically.
Place two terminal windows beside each other during release review. The left side should show the final accepted second with policy version clock-v3. The right side should show the first rejected second, the same token fingerprint, and zero provider dispatches.
Distributed verifiers need consistent evidence
Run every boundary fixture through the production load balancer. Pin repetitions to replica A and replica B, then repeat during a rolling restart and a clock-synchronization disturbance. The same effective timestamp must produce the same decision under the same policy version.
The protected event should carry the token fingerprint, trusted issuer policy ID, audience result, raw exp, raw nbf, optional iat, verifier timestamp, measured host offset, configured leeway, validation-library version, and final reason. Exclude the raw bearer token while preserving enough arithmetic for an investigator to reproduce the decision without access to application memory.
Use distinct reasons such as token_expired, token_not_yet_valid, time_claim_type_invalid, time_claim_missing, and verifier_clock_untrusted. A public invalid_token response can remain stable. The protected detail supports operations without exposing policy thresholds to an unauthenticated caller.
Release evidence should also show zero model dispatches for rejected fixtures. Authentication logs alone prove a verifier opinion. Provider-side request IDs or adapter counters prove that expired and premature tokens stopped before LLM processing.
DeepInspect
DeepInspect operates on authenticated HTTP requests deliberately routed between users or agents and LLM endpoints. The authorization server and resource-server verifier own token issuance, synchronized clocks, signature validation, and the exp and nbf decision. Direct provider calls, local model execution, STDIO tools, and unrouted HTTP paths retain separate owners.
After upstream validation, DeepInspect can evaluate the resolved identity with route, model, tenant, and data classification under versioned policy. Its per-request decision record can carry a correlation reference to the verifier event, while keeping the time-claim arithmetic with the component that performed it. That split shows which control rejected the token and which control authorized the routed model request.
Book a demo today.
Frequently asked questions
- How much clock skew should an LLM API allow?
Choose the smallest value supported by measured offset across the issuer and every production verifier. RFC 7519 permits small leeway and describes a few minutes as the usual upper shape, while leaving the exact deployment choice open. A team with sub-second synchronized hosts may select seconds rather than minutes. Record the measurement window, alert threshold, policy owner, and review date. Revisit the value when infrastructure, identity providers, or regions change. A larger allowance should require a security decision because it extends the accepted bearer-token interval and advances the effective
nbfboundary.- Should leeway apply to exp and nbf equally?
One symmetric value is simpler to reason about and test. It moves the effective expiration boundary later and the effective not-before boundary earlier by the same measured allowance. A profile can define different treatment, but that choice needs explicit expressions, separate fixtures, and a reason tied to issuer behavior. Hidden asymmetry inside a library wrapper produces surprising acceptance windows. The release artifact should state the exact comparisons used by the deployed verifier.
- Does iat receive the same clock-skew allowance?
RFC 7519 defines
iatas issuance time and permits using it to determine token age. The base claim definition supplies no universal future-time or maximum-age validation rule. A token profile may define those checks and may reuse the measured allowance for futureiatvalues. Document the decision separately. Keepiatage failures distinct from expiration and not-before failures so the event explains which contract rejected the token.- What happens when a verifier clock drifts beyond policy?
The verifier should enter the deployment's documented unhealthy state. A common fail-closed design removes the replica from service and rejects authentication if it continues receiving traffic. Record
verifier_clock_untrustedrather than misclassifying every request as expired. Alert on the offset and the affected replica. The acceptance suite should force an out-of-bound clock and prove that no authenticated principal or model dispatch emerges from that host.- Should an accepted stream stop when the token expires?
The API contract decides this behavior. Many systems authenticate and authorize at request admission, then let the accepted operation finish. A privileged follow-on action or a new HTTP request needs a fresh decision. Long-lived streams may justify periodic reauthorization when the protocol and product define it. State the chosen checkpoint, test it, and avoid implying that the JWT standard dictates stream termination semantics.