invalid_grant error during token refresh with clock skew

Resolving Clock Skew in Token Refresh

There is no single industry-standard window for clock skew leeway because the OAuth 2.0 specification does not mandate a specific grace period. However, most production Authorization Servers implement a leeway of 30 to 300 seconds to account for minor drift. When a client's clock is ahead of the server's, the client may believe a token is still valid, but the server rejects the refresh request with an invalid_grant error because its own clock indicates the token has already expired.

Likely Cause vs. Confirmed Fact

While invalid_grant is the confirmed response for an expired refresh token, it is also used for revoked tokens or invalid grant types. Clock skew is the likely cause only if the error occurs consistently at the very edge of the token's expiration window and is resolved by synchronizing the system clock.

Implementation Steps to Prevent Premature Expiration

To prevent invalid_grant errors without relying on the server's internal leeway, implement the following strategies:

• Client-Side Proactive Refresh: Do not wait for the exact exp timestamp. Trigger the refresh flow when the token has 5–10% of its lifetime remaining or at least 5 minutes before expiration.
• System-Level Synchronization: Ensure the client environment uses NTP (Network Time Protocol) to maintain synchronization with a trusted time source.
• Calculate Server Offset: If you cannot control the system clock (e.g., in restricted environments), programmatically determine the offset using the Date header from the server's responses.

Programmatic Offset Calculation

You can calculate the drift by comparing the local system time to the Date header returned in the HTTP response of the token request:

// Simplified logic for calculating drift
const serverDate = new Date(response.headers.get('Date'));
const localDate = new Date();
const offset = serverDate.getTime() - localDate.getTime();

// Use this offset when calculating if the token is expired
const isExpired = (tokenExpTimestamp + offset) < Date.now();

Verification Commands

To verify if clock skew is the root cause, compare your system time against a trusted NTP source:

# Query an NTP server to check for drift (Linux/macOS)
ntpdate -q pool.ntp.org

Diagnostic Detail Needed: Are you running the client in a containerized environment (e.g., Docker/Kubernetes)? Container clock drift can differ from host drift and may require specific runtime configurations.