Refresh tokens & rotation

Refresh tokens are how a client stays logged in past the 15-minute access-token window. They are opaque UUIDs (not JWTs), they live in PostgreSQL, and they rotate on every use.

When to refresh

A client should call /refresh when its access token is about to expire. Two common patterns:

• Eagerly — a few seconds before exp, in a background timer.
• Reactively — on the first request that returns TOKEN_EXPIRED.

Either works. Reactive is simpler to implement; eager keeps the user from ever seeing a 401.

The refresh request

POST /api/v1/refresh
Content-Type: application/json

{ "refreshToken": "8c9a3a48-7b9d-..." }

There is no Authorization header — the refresh token is the credential.

What the server does

UPDATE refresh_tokens
SET revoked_at = NOW(), revoke_reason = 'TOKEN_ROTATION'
WHERE id = $1;

INSERT INTO refresh_tokens (id, user_id, tenant_id, token_hash, expires_at, ...)
VALUES (...);

{
  "success": true,
  "data": {
    "accessToken": "<new-jwt>",
    "refreshToken": "<new-uuid>",
    "expiresIn": 900,
    "user": { "...": "..." }
  }
}

Why rotation matters

If a refresh token is leaked, the attacker gets exactly one use out of it — the moment the legitimate client refreshes, the leaked token is revoked. This is the same property classic banking apps rely on.

Failure modes

If you ever see INVALID_TOKEN on a token you just received, the most likely cause is that a second client rotated the same token first — which is the exact pattern you want to detect on a stolen token.

Sessions and rotation

Rotation is a per-token concern. Session limits are a per-user concern. They combine like this:

• A refresh never adds a session — it replaces one.
• A login can add a session, and may evict the oldest one if the limit is hit. See Sessions for the full atomic flow.

So a user with maxConcurrentSessions = 5 and 5 active devices can rotate their tokens forever. Logging in from a 6th device will revoke the oldest.

Implementation tips