About OAuth Token Expiry
OAuth tokens have a limited lifespan for security purposes. The expires_in value in OAuth responses indicates how many seconds until the access token expires. To ensure uninterrupted API access, you should refresh tokens before they expire.
How This Calculator Works
This calculator helps you determine the optimal time to refresh your OAuth tokens by applying a buffer percentage. Instead of waiting until the last second, refreshing early provides a safety margin against network delays and processing time.
Refresh Time = expires_in x (1 - buffer%)
Recommended Buffer Values
- 5-10% - Standard applications with reliable network connections
- 10-15% - Applications with variable network conditions
- 15-20% - Critical systems requiring high reliability
Common Token Lifetimes
- 3600 seconds (1 hour) - Google, Microsoft, and most OAuth providers
- 7200 seconds (2 hours) - Some enterprise applications
- 86400 seconds (24 hours) - Long-lived tokens for background services
What Happens When a Token Expires
When an access token expires and your application tries to use it, the API server returns an HTTP 401 Unauthorized response. The specific error body varies by provider — Google returns {"error": "invalid_token"}, GitHub returns {"message": "Bad credentials"} — but the HTTP status is consistently 401. If your application doesn't handle this gracefully, the user sees a broken experience: a failed API call, a blank page, or an error dialog. The correct behavior is either to silently refresh the token using a refresh token and retry the request, or to prompt the user to sign in again if no refresh token is available.
Access Tokens vs. Refresh Tokens
OAuth 2.0 uses two distinct token types with different lifespans and purposes:
- Access token — a short-lived credential (typically 1 hour) that your application sends with every API request. It's included in the HTTP
Authorization: Bearer <token>header. Because it's sent frequently, it's deliberately short-lived; if it's intercepted, the exposure window is small. - Refresh token — a long-lived credential (days to months, sometimes indefinite) that is stored securely and never sent to the API directly. Its only job is to obtain a new access token from the authorization server when the current one expires. Refresh tokens can be revoked by the server at any time, for example when a user signs out or revokes application access.
Not all OAuth flows issue refresh tokens. The Implicit flow (now deprecated) and some Client Credentials flows do not. If your provider doesn't issue a refresh token, users must re-authenticate when the access token expires.
JWT Structure and the exp Claim
Many OAuth access tokens are JSON Web Tokens (JWTs), a self-contained format that encodes claims — including expiry — in the token itself. A JWT has three Base64URL-encoded parts separated by periods: header.payload.signature. The payload section contains standard claims including exp (expiration time as a Unix timestamp), iat (issued-at time), and sub (subject, usually the user ID). To check a JWT's expiry time without calling the server, decode the middle section with Base64 and parse the exp field. For example, exp: 1700000000 means the token expires at Unix timestamp 1700000000 (you can paste this into a Unix timestamp converter). Your application can read this locally to determine when to schedule a refresh without an extra network round-trip.
Proactive vs. Reactive Token Refresh
There are two strategies for keeping tokens current:
- Proactive (timer-based): When you receive a token, calculate the refresh time using a buffer (e.g.,
expires_in × 0.9) and set a timer to refresh before expiry. This is the more robust approach — the user never encounters a 401 because the token is always refreshed ahead of need. - Reactive (retry on 401): Make API calls with the current token. If you receive a 401, attempt to refresh the access token and retry the original request once. This is simpler to implement but can cause one failed request per expiry cycle, which may be visible to the user as a momentary delay.
Pseudocode: Proactive Token Refresh
// On receiving a new token from the OAuth server:
function onTokenReceived(tokenResponse) {
accessToken = tokenResponse.access_token
bufferFraction = 0.10 // refresh at 90% of lifetime
refreshAfterMs = tokenResponse.expires_in * (1 - bufferFraction) * 1000
clearTimeout(refreshTimer)
refreshTimer = setTimeout(refreshAccessToken, refreshAfterMs)
}
// Refresh function calls the token endpoint with the refresh token:
async function refreshAccessToken() {
response = await POST("/oauth/token", {
grant_type: "refresh_token",
refresh_token: storedRefreshToken,
client_id: CLIENT_ID
})
if (response.ok) {
onTokenReceived(response.body) // resets the timer
} else {
promptUserToSignIn() // refresh token was revoked
}
}
OAuth Refresh Quick Reference
The expires_in value in an OAuth 2.0 token response is the lifetime in seconds (RFC 6749). A fixed buffer protects against clock skew and network delay.
| Token lifetime | 10% buffer | 60 second buffer | 5 minute buffer |
|---|---|---|---|
| 5m (300 s) | 4m 30s | 4m | Too short |
| 15m (900 s) | 13m 30s | 14m | 10m |
| 1h (3,600 s) | 54m | 59m | 55m |
| 2h (7,200 s) | 1h 48m | 1h 59m | 1h 55m |
| 24h (86,400 s) | 21h 36m | 23h 59m | 23h 55m |