Security & Identity

Refresh Token Rotation

Subtitle: Short-lived access, single-use refresh, revoke the family on reuse

Panel 1 - Full-width swimlane sequence diagram. Actors: APP | AUTH SERVER | TOKEN FAMILY | API
Login returns access token (5 min) + refresh RT1
Access token expires, APP presents RT1
Server validates RT1, marks it USED
Server issues new access token + RT2, same family
Stolen RT1 replayed, reuse detected, family revoked

Panel 2 - Why rotate at all:

Refresh tokens are long-lived and high value Public apps cannot hide a client secret A bearer token works for whoever holds it Rotation shrinks the stolen-token window Single use makes theft observable

Panel 3 - Rules that make it work:

Access token in minutes, refresh in days Every refresh token is single use Chain tokens into one family ID Reuse of a spent token revokes the family Store token hashes, never raw values

Panel 4 - Common mistakes:

One long-lived refresh token, never rotated Rotating but not revoking on reuse No family ID, so only one token dies Parallel tabs cause false revokes, add a grace window Refresh token in localStorage instead of httpOnly cookie