Refresh a token
Trade a valid refresh token for a new access + refresh token pair, without re-sending your api key.
This and /auth are the only endpoints that do not require a bearer token — the refresh token is the credential here, so it is sent in the body rather than the Authorization header.
Refresh tokens rotate
Each call consumes the token you present and issues a new one. A refresh token is single-use: once spent, it is dead. Always store the refreshToken from the response and discard the one you just sent.
Replay revokes the whole chain
Presenting an already-consumed token is the signature of a stolen one, so the service revokes the entire rotation family — the token you sent, the one that replaced it, and every descendant. Both you and the attacker are forced back to /auth with your api key.
In practice this means a refresh token must be stored durably and refreshed by exactly one process. Two workers sharing a refresh token will race, one will replay, and both get logged out.
Headers
Correlation id. Generated if omitted, echoed on every response, and written to the audit log. /send is the exception — there it is required, and it doubles as the idempotency key.
Request
Opaque 64-character hex token. Single-use — every /refresh consumes the token presented and returns a new one.
It is not a JWT and carries no readable claims. Only a hash of it is stored, so it cannot be recovered if lost — a lost refresh token just means calling /auth again.
Response
Echo of the inbound X-Request-Id, or a generated one.