Refresh a session
Exchanges a refresh token for a new pair.
- Authentication
- None
- Retries
- Idempotency-Key
- Body
- application/json
- Version
- 2026-09-03
Rotates: the presented token is spent, and presenting it again revokes the whole session family - unless it is the same browser a few seconds later, which is two tabs rather than a thief. See auth_service for both rules.
The session stays in the workspace its token family carries, so a switch made an hour ago is still in force.
While a staff support session is open in this browser (ic_support), the customer surfaces get a token for that workspace instead - see _support_token_response. The refresh cookie is not rotated then.
Headers#
Request body#
Responses#
Errors#
Failures use one envelope on every endpoint, described in Retries, versioning and limits. The codes you are most likely to meet here:
validation_error· 422 — The payload was well-formed JSON but failed schema validation.idempotency_key_reused· 422 — This `Idempotency-Key` was used before, for a request with a different body.rate_limited· 429 — Too many requests in the current window. The limit is per workspace, and some endpoints add a per-agent limit on top.
More Auth endpoints#
Something unclear or missing? Tell us and we’ll fix it.