`POST /auth/api/refresh`

Rotate an expiring access token using the refresh token alone.

Old refresh token is invalidated on success; reuse is treated as a leak (see below).

Use case

On 401 from a protected endpoint: refresh, swap tokens in cache, retry once. If refresh also 401s, fall back to /auth/api/token.

Body

Field	Type	Required	Description
`refreshToken`	string	yes	Refresh token from the previous pair.

Response `200`

Same shape as POST /auth/api/token. The old refresh token is revoked immediately.

Single-use guarantee

Reusing a refresh token that has already been rotated is treated as a leak: every token for the client account is revoked and the caller gets 401 Token reuse detected. Re-issue via POST /auth/api/token with the API key to recover.

Errors

Status	Meaning
`400`	Missing `refreshToken`.
`401`	Invalid / revoked / expired / reused.
`403`	API deactivated between issuance and refresh.

Example

curl -X POST "$BASE_URL/auth/api/refresh" \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "…" }'

Use case​

Body​

Response 200​

Single-use guarantee​

Errors​

Example​