Implement Frontend Token Refresh

---
name: "refresh-token-in-frontend"
description: "Design and review secure access-token refresh flows for browser applications, including HttpOnly refresh cookies, request retry queues, rotation, SSR, and logout."
---

# Implement Frontend Token Refresh

Use this skill when designing, implementing, or reviewing a browser authentication flow that renews short-lived access tokens.

## Required security model

- Keep the refresh token in a `Secure`, `HttpOnly`, appropriately scoped cookie.
- Keep the access token short-lived and preferably in application memory.
- Require HTTPS in production.
- Implement refresh-token rotation and reuse detection on the server.
- Treat authorization as a server responsibility; frontend guards only improve UX.

## Establish the contract first

Confirm login, refresh, logout, and session endpoints; cookie attributes; CSRF defense; access-token response shape; expiration behavior; and whether the app uses CSR, SSR, or both. Do not invent a client-only fix for a missing server guarantee.

## Client workflow

1. Send the access token on protected API requests when one is available.
2. On an eligible authentication failure, start at most one refresh request.
3. Queue concurrent failed requests behind that refresh operation.
4. If refresh succeeds, update the in-memory token and retry each original request once.
5. Mark retried requests to prevent infinite refresh loops.
6. If refresh fails, clear local session state, reject queued requests, and move the user to the signed-out flow.
7. On logout, call the server endpoint that invalidates the refresh session and clears its cookie, then clear client state.

## Exclusions and edge cases

- Never intercept the refresh request itself as a refresh candidate.
- Distinguish expired authentication from forbidden authorization; do not refresh every `403` or arbitrary `401` without an API contract.
- Cancel or ignore stale work when the user logs out during refresh.
- Avoid replaying non-idempotent requests unless the request body is safely reusable and the API contract permits it.
- In SSR frameworks, keep tokens on the server side of the boundary and avoid leaking credentials into serialized props or logs.

## Validation

Test normal requests, a single expired token, several simultaneous failures, refresh rejection, rotation, logout during refresh, retry-loop prevention, page reload, and SSR behavior when applicable. Report which guarantees belong to the backend and which were verified in the frontend.