Exchange a refresh token for a new access token

POST 
/auth/refresh

Rotates the refresh-token family — the presented token is single-use and yields a new pair. Reuse of a previously-rotated token invalidates the whole session family (token theft detection). Public endpoint, throttled to 30/min/IP.

Request

Responses

200

Fresh access + refresh tokens.

201

Resource created. Body follows the shared { data, meta } envelope; data is the newly-created resource.

400

The request payload failed validation. error.details lists the offending fields with human-readable messages and the class-validator constraint that fired. Fix the payload and retry — this is not a transient failure.

401

Refresh token invalid, expired, or reuse detected — the session family is revoked.

409

The request conflicts with the current state of the target resource — a duplicate unique field on registration, an idempotency-key replay with a different payload, or a webhook eventId that has already been processed. error.code may be CONFLICT or IDEMPOTENCY_CONFLICT depending on the cause.

429

Rate limit exceeded. Global default is 120 requests/minute per IP; auth-flow, OTP, self-registration, WebAuthn, IRA lookup, and public-lead endpoints carry tighter per-endpoint limits. Retry after the delay indicated by the Retry-After header.

Response Headers

Retry-After

Seconds to wait before retrying.

500

Unhandled server error. The response carries a meta.requestId correlator you can hand to platform operations to trace the failure through structured logs and the hash-chained audit trail. Retry with the same Idempotency-Key header if the endpoint accepts idempotency.