---
title: "Refresh an access token"
method: POST
path: "/api/v1/auth/refresh"
tags: ["auth"]
---

# Refresh an access token

`POST /api/v1/auth/refresh`

Exchanges a valid refresh token for a new access token and a new refresh token,
rotating the refresh token on every call. The response also includes the updated
user object. Store the new refresh token and discard the old one.

Refresh tokens are single-use — submitting an already-consumed token returns HTTP 401.
Rate limiting is applied per (user, IP) pair when the token can be verified, and
falls back to IP-only when it cannot. The limit is 30 exchanges per minute per
bucket; exceeding it returns HTTP 429.

## Request body

- object
  - `refresh_token` string, required — Refresh token previously issued by a login, registration, or token-refresh response.

## Response `200`

Successful response

- AuthTokens — Credential bundle returned after a successful authentication exchange. Contains the access token, refresh token, and the authenticated user.
  - `expires_in` integer, required — Number of seconds until `token` expires. After this period, use `refresh_token` to obtain a new access token.
  - `metadata` object — Optional auxiliary data associated with this authentication event, such as `onboarding_job_id` when the user is completing onboarding. `null` when no extra context is present.
  - `refresh_token` string, required — Long-lived opaque refresh token. Use this to obtain a new access token when `token` expires.
  - `token` string, required — Short-lived JWT access token. Include this value in the `Authorization: Bearer <token>` header for all authenticated API requests.
  - `token_type` string, required — Token scheme. Always `"Bearer"`.
  - `user` User, required — A platform user account. Represents a human or system actor that can own threads, belong to an organization, and interact with the API.
    - `alias` string — Short handle or alias for the user. `null` if not set.
    - `app` string — ID of the app this user (and their access token) is scoped to (`dap_...`). `null` if the user is not scoped to an app.
    - `app_name` string — Display name of the user's app. `null` when the app association was not preloaded by the caller.
    - `email` string — Email address of the user.
    - `id` string, required — User ID (`usr_...`).
    - `is_system_user` boolean — `true` if this account is an internal system user rather than a human. System users are created automatically by the platform.
    - `metadata` object — Arbitrary key-value metadata attached to the user. Defaults to an empty object.
    - `name` string — Full display name of the user. `null` if the user has not set a name.
    - `org` string — ID of the organization this user belongs to (`org_...`). `null` if the user is not a member of any organization.
    - `org_name` string — Display name of the user's organization. `null` when the user is not in an org, or when the org association was not preloaded by the caller.
    - `org_role` string — Role of the user within their organization. One of `"admin"`, `"member"`, or `"viewer"`. `null` when the user is not a member of any organization.
    - `sandbox` string — ID of the sandbox environment this user is scoped to (`sbx_...`). `null` for production users.
    - `sandbox_name` string — Display name of the user's sandbox environment. `null` for production users, or when the sandbox association was not preloaded by the caller.

## Other responses

- `401` — Invalid or expired refresh token
- `429` — Rate limited

---

[API](https://skmtc.net/archastro/apis/archastro-platform-api.md) · [All operations](https://skmtc.net/archastro/apis/archastro-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/archastro/archastro-platform-api/revisions/a8772b442f86/schema)