---
title: "Refresh a session"
method: POST
path: "/v1/auth/refresh"
tags: ["Auth"]
---

# Refresh a session

`POST /v1/auth/refresh`

## Request

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

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.

## Request body

- RefreshRequest: Send an empty object from a browser — the httpOnly `refresh_token` cookie is presented instead, and takes over when the body omits the field.
  - `refresh_token` string

## Response `200`

A new session (access + rotated refresh).

- AuthSession: A short-lived access JWT plus a rotating refresh token. The refresh token is also set as an httpOnly, SameSite=Lax cookie scoped to `/v1/auth` (Secure whenever the connection is https), which is what carries a browser session across a reload; the body copy is for clients with no cookie jar, such as the CLI.
  - `token_type` 'Bearer', required
  - `access_token` string, required: Short-lived access JWT. Send as `Authorization: Bearer <token>`.
  - `expires_in` integer, required: Access-token lifetime in seconds.
  - `refresh_token` string: Single-use refresh token, rotated on every refresh.
  - `user` User, required
    - `id` string, required: Public user ID (user_ prefix).
    - `email` string, email, required
    - `name` string, nullable
    - `email_verified` boolean, required
    - `roles` string[], required: Roles on naturali itself, not on a project. Empty for almost every account; `admin` marks a naturali operator. Changed only through `PUT /v1/admin/users/{user_id}/roles`, by a caller holding the role that grants each one.
    - `usage_alerts` boolean, required: Whether the account is emailed when its model credit, runs or indexed storage reaches 75%, 90% and 100%. On for a new account.
    - `created_at` string, date-time, required

## Other responses

- `401`: The refresh token is invalid, expired or was reused.

---

[API](https://skmtc.dev/naturali/apis/naturali-ai-api.md) · [All operations](https://skmtc.dev/naturali/apis/naturali-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/naturali/apis/naturali-ai-api/revisions/e4905b78f422?raw)