Auth

Refresh a session

Exchanges a valid refresh token for a new access JWT and a rotated refresh token, taken from the body or from the refresh_token cookie set at sign-in — a browser sends an empty body and the cookie carries the credential. Refresh tokens are single-use; presenting a previously-rotated token is treated as reuse and revokes the whole session family (createRefreshRotation reuse detection), except within a few seconds of the rotation, where it is treated as two tabs racing on one cookie and rotated again.

post/v1/auth/refresh

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/auth/refresh
  • Auth: none required

Request body

refresh_tokenstring

Example request

{
  "refresh_token": "rt_9f2StGXR8Z5jdHi6B..."
}

Response

A new session (access + rotated refresh).

token_type'Bearer' required
access_tokenstring required

Short-lived access JWT. Send as Authorization: Bearer <token>.

expires_ininteger required

Access-token lifetime in seconds.

refresh_tokenstring

Single-use refresh token, rotated on every refresh.

Example response

{
  "token_type": "Bearer",
  "access_token": "eyJhbGciOiJIUzI1NiJ9...",
  "expires_in": 900,
  "refresh_token": "rt_9f2StGXR8Z5jdHi6B...",
  "user": {
    "id": "user_V1StGXR8Z5jdHi6B",
    "email": "ana@acme.com",
    "name": "Ana Silva",
    "email_verified": true,
    "roles": [],
    "usage_alerts": true,
    "created_at": "2026-07-17T00:00:00.000Z"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.