POST /v1/auth/refresh

Exchange a refresh token for a new access token. Refresh tokens rotate on every successful call.

::: tip Auth Required: identsphere_rt cookie. The access token is NOT required (and is usually expired by the time you call this). :::

Request

POST /v1/auth/refresh

Header	Required	Notes
Cookie: identsphere_rt=...	yes	The refresh token cookie issued at login.

No request body.

Response

200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_in": 900
}

Cookies updated:

• identsphere_at — new access token
• identsphere_rt — rotated refresh token (old one is now invalid)
• identsphere_csrf — new CSRF token

Error responses

Status	Code	When
401	authentication_required	Refresh cookie missing, doesn't match any row, the row is revoked, or the refresh token has expired.
500	internal_error	Database failure.

Example: curl

curl -X POST https://auth.example.com/v1/auth/refresh \
  -b cookies.txt \
  -c cookies.txt

Example: TypeScript (@identsphere/react)

The Axios client built by createAxiosClient runs refresh automatically on 401 responses; you should not need to call this directly.

// If you're not using the included client:
const res = await fetch('https://auth.example.com/v1/auth/refresh', {
  method: 'POST',
  credentials: 'include',
});
if (res.ok) {
  // retry the original request
}

Notes

::: warning Family detection Refresh tokens rotate on every use. Replaying a previously-rotated refresh token finds no matching row and returns 401 — but more importantly, in a future version this will also revoke the entire session family on suspicion of compromise. Always use the most recently received refresh token; never store an old one as a fallback. :::

• The refresh cookie has the path scope set to route_prefix (default /v1/auth) — your app's other endpoints don't see this cookie at all.
• A refresh does NOT extend the absolute session lifetime; it only renews the short-lived access token. The refresh token's own expiry is set at login time (default 30 days).
• A revoked session (via POST /v1/auth/logout or DELETE /v1/auth/sessions) refuses to refresh even within its lifetime.