---
title: "Exchange a one-time login token for session tokens"
method: POST
path: "/api/v1/auth/token"
tags: ["auth"]
---

# Exchange a one-time login token for session tokens

`POST /api/v1/auth/token`

Consumes a single-use login token delivered via email and returns an access token,
refresh token, and the authenticated user object. One-time tokens are issued by the
passwordless login flow and expire after a short window; submitting an expired or
already-used token returns HTTP 401.

If `timezone` is provided and the user's current timezone is still the default
(`"America/Los_Angeles"`), the account timezone is updated in the same request.
Requests are rate-limited to 10 per IP per minute; exceeding this returns HTTP 429.

## Request body

- object
  - `timezone` string — IANA timezone name to apply to the account if the account timezone is still the default, e.g. `"Europe/London"`. Omit to leave the timezone unchanged.
  - `token` string, required — Single-use login token extracted from the magic link or email code flow.

## 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

- `400` — Missing token
- `401` — Invalid or expired token
- `429` — Rate limited
- `500` — Token exchange failed

---

[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)