What You'll Learn
- Why access tokens expire quickly
- How refresh tokens extend sessions safely
- How scopes limit what a token can do
- How to handle expired tokens in your client code
Why This Matters
Tokens that never expire are a security nightmare — if stolen, the thief has access forever. Tokens that expire every 5 minutes are unusable — users must re-log in constantly. The OAuth 2.0 solution is a two-token system: short-lived access tokens for security, long-lived refresh tokens for usability. Understanding this split is essential for building any authenticated app.
The Two-Token System
| Token | Lifetime | Purpose | Revocable? |
|---|---|---|---|
| Access token | Short (15 min – 1 hour) | Call the API | Hard — valid until exp |
| Refresh token | Long (days – weeks) | Get new access tokens | Yes — server can revoke |
Why Access Tokens Are Short-Lived
If an access token is stolen (via XSS, leaked logs, network interception), the thief has access until it expires. A 1-hour expiration limits the damage to 1 hour. A 30-day expiration gives the thief a month.
Short lifetimes also let the server change permissions quickly. If the user's role changes from admin to regular user, the next access token they get will have the new role — within an hour at most.
Why Refresh Tokens Exist
Short-lived access tokens would force users to log in every hour. That is unusable. Refresh tokens solve this:
- At login, the server issues both an access token (1 hour) and a refresh token (30 days).
- The client uses the access token for API calls.
- When the access token expires, the client uses the refresh token to get a new one — silently, without bothering the user.
- The user stays logged in for 30 days (or until they explicitly log out).
The Refresh Flow
# Access token expired — get a new one
POST /oauth/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded
grant_type=refresh_token&
refresh_token=1//abc123&
client_id=YOUR_ID&
client_secret=YOUR_SECRET
# Response
{
"access_token": "eyJhbGciOi...",
"token_type": "Bearer",
"expires_in": 3600
}
The client gets a new access token. The user is not prompted. The refresh token may also be rotated (a new one returned with each refresh) for added security.
Why Refresh Tokens Are Revocable
Unlike JWTs (which are stateless and cannot be revoked before exp), refresh tokens are stored server-side. When the user clicks "Log out" or "Revoke access", the server deletes the refresh token. The current access token is still valid until it expires (an hour at most), but no new ones can be issued.
Scopes — Limiting What a Token Can Do
Scopes are permissions attached to a token. They tell the API what the token's holder is allowed to do.
How scopes are requested
GET /oauth/authorize?
response_type=code&
client_id=YOUR_ID&
scope=read:user user:email& ← requested scopes
...
How scopes appear in tokens
JWTs often include scopes in the payload:
{
"sub": "123",
"scope": "read:user user:email",
"exp": 1724557200
}
How the API checks scopes
# Pseudocode
def delete_post(user, post_id):
if "write:posts" not in user.token.scopes:
return 403 Forbidden
# ... proceed with delete
Handling Expired Tokens in Client Code
Real clients must handle the case where the access token expires mid-session:
// JavaScript example
async function callApi(url) {
let response = await fetch(url, {
headers: { "Authorization": `Bearer ${accessToken}` }
});
if (response.status === 401) {
// Access token may have expired — try refreshing
const newToken = await refreshAccessToken();
if (newToken) {
accessToken = newToken;
// Retry the original request
response = await fetch(url, {
headers: { "Authorization": `Bearer ${accessToken}` }
});
} else {
// Refresh failed — user must log in again
redirectToLogin();
return;
}
}
return response;
}
async function refreshAccessToken() {
const response = await fetch("/oauth/token", {
method: "POST",
headers: { "Content-Type": "application/x-www-form-urlencoded" },
body: new URLSearchParams({
grant_type: "refresh_token",
refresh_token: refreshToken,
client_id: CLIENT_ID
})
});
if (response.ok) {
const data = await response.json();
return data.access_token;
}
return null;
}
Token Storage — Where to Keep Tokens
| Storage | Pros | Cons |
|---|---|---|
| localStorage | Easy to access from JS | Vulnerable to XSS |
| HttpOnly cookie | JS cannot read — safe from XSS | Vulnerable to CSRF (mitigate with SameSite) |
| In-memory (JS variable) | Lost on page reload | Most secure — use with refresh tokens in HttpOnly cookies |
| SessionStorage | Cleared when tab closes | Vulnerable to XSS |
For high-security apps: store refresh tokens in HttpOnly cookies, keep access tokens in memory only. The user stays logged in (refresh works), but a stolen access token dies when the page closes.
Common Mistakes
- Long-lived access tokens. A 30-day access token is a 30-day security risk. Use 1-hour access tokens + 30-day refresh tokens.
- Not handling 401. If your client does not refresh on 401, users must re-log in every hour.
- Refreshing on every request. Wastes server resources. Only refresh when you get a 401.
- Storing refresh tokens in localStorage. A single XSS hole gives attackers long-lived access. Use HttpOnly cookies.
- Not rotating refresh tokens. If a refresh token is stolen, it works for 30 days. Rotate it on each use so the stolen one becomes invalid.
- Requesting too many scopes. Users will deny the login. Ask for the minimum.
Practical Exercise (10 minutes)
Decode a JWT (use jwt.io) and find:
- The
expclaim. Convert it to a human-readable date. - The
scopeorscopesclaim. List the scopes. - The
iat(issued at) claim. How long is the token valid?
Then design the refresh strategy: when does your client refresh? What happens if the refresh fails? When does the user have to log in again?
Mini Challenge
Build a simple client that: (1) gets an access token and refresh token from a login endpoint, (2) makes an API call, (3) waits for the access token to expire (or shortens the expiration for testing), (4) automatically refreshes and retries. Test that the user is not interrupted.
Key Takeaways
- Access tokens are short-lived (1 hour) for security. Refresh tokens are long-lived (30 days) for usability.
- Refresh tokens are stored server-side and revocable. Access tokens (JWTs) are stateless and cannot be revoked before exp.
- Scopes limit what a token can do. Always request the minimum.
- Handle 401 in your client: try to refresh, retry, redirect to login if refresh fails.
- Store refresh tokens in HttpOnly cookies. Keep access tokens in memory for high-security apps.
Previously: Lesson 30 introduced OAuth 2.0.
Today: You learned the day-to-day reality of token management — expiration, refresh, and scopes.
Next: Module 5 is complete. Module 6 begins with lesson 32 — What Is API Testing?.
FAQ
What is the difference between logout and revoke?
Logout is what the user does — they end their session in the client. The client discards its tokens. Revoke is what the server does — it invalidates the refresh token so it cannot be used to get new access tokens. A proper logout calls the revoke endpoint, otherwise the refresh token remains valid until it expires.
Should I rotate refresh tokens?
Yes. Each time you use a refresh token, the server should issue a new one and invalidate the old. This means a stolen refresh token becomes useless after the legitimate user refreshes. Implemented by OAuth providers like Google and Auth0.
Comments
Comments
Post a Comment