Use response headers for token refresh
ADR-0027
Use response headers for token refresh
Context
Key rotation (ADR-0026) means tokens can end up signed by deprecated keys. Mobile clients need updated tokens without explicit refresh requests or authentication interruptions.
Decision
Deliver refreshed tokens via X-New-Token response header. The backend includes a new token under two conditions:
- Deprecated key — the token is valid but signed with a deprecated key (security requirement)
- Age threshold — the token is older than 24 hours (sliding window optimization)
No explicit refresh endpoint. Clients process the header through existing Apollo interceptors (ADR-0018) and store the new token.
Consequences
Token refresh happens transparently during normal API usage. No extra network requests, no user interaction. The 24-hour age threshold keeps overhead low — most requests don't trigger a refresh.
The client must process the refresh header correctly; missing it means the token eventually ages out and forces re-authentication.