POST
Refresh tokens (rotation)

Overview

Exchanges a valid refresh token for a new access + refresh pair and invalidates the presented token in the same transaction. Refresh tokens are single-use rotating — the server marks the old row as usedAt = now and links it to the new row via replacedBy. Re-presenting an already-used refresh token is treated as theft: the entire session chain (every refresh token sharing the same sessionId) is revoked and the API returns 401 TOKEN_REVOKED. The access token returned is a fresh RS256 JWT with a 15-minute TTL. The refresh token is a new 256-bit opaque base64url string with a 30-day TTL.

Authentication

None required at the HTTP layer — the refresh token itself is the credential. Do not send Authorization: Bearer ... on this call.

Path parameters

None.

Query parameters

None.

Request body

Example payload

Response — 200 OK

Example response

Error responses

Example error — 401

Side effects

  • Marks the presented refresh_tokens row with usedAt = now and replacedByTokenId = <new id>.
  • Inserts a new refresh_tokens row sharing the same sessionId and deviceFingerprint.
  • On reuse detection, calls revokeAllForSession(sessionId) — every refresh token for that session is revoked.

See also

  • Authentication — full token lifecycle.
  • Login — issues the initial token pair.
  • Logout — revoke the current session’s refresh token.
  • Errors — stable error code catalog.

curl