Refresh the access token
POST/auth/refresh
Refresh token. Not your access token — the refresh token, from the HttpOnly cookie in a browser or from the login response body on native.
Trades a refresh token for a fresh access token, without asking the person for their password again.
The refresh token rotates. Every call returns a new one — in the Set-Cookie for browsers, in the body for X-Client: mobile — and the one you sent is spent. Store the new one
before the next call.
Presenting a token that was already spent is treated as theft, not as a retry: the whole session family is revoked and the person has to sign in again. Do not send refreshes concurrently from two places.
Request
Responses
- 200
- 400
- 401
- 403
- 404
- 409
- 422
- 500
OK
Malformed request — validation failure, or a header such as Idempotency-Key is missing or not a UUID.
Missing, expired, or untrusted bearer token.
Authenticated but not permitted — the caller's role or scope does not grant this operation, or the resource belongs to another tenant.
The referenced wallet, transaction, user, or tenant does not exist within the caller's tenant.
Idempotency conflict — a request with this Idempotency-Key is still in flight. Retry once it settles. A key belonging to an already-completed request is NOT an error: the original response is replayed with its original status.
The request is well-formed but violates a business rule — for example a posting that would breach a wallet fund's balance floor, a transaction type not enabled for the tenant, a per-transaction or daily issuance cap, or an operation on a frozen wallet.
Unexpected server error.