---
title: "Verify a magic link token"
method: POST
path: "/api/v1/auth/verify/link"
tags: ["auth"]
---

# Verify a magic link token

`POST /api/v1/auth/verify/link`

Consumes a single-use token from a magic link URL and returns an access token,
refresh token, and the authenticated user object. This endpoint completes both the
login flow (initiated by `/auth/request_login_link`) and the registration flow
(initiated by `/auth/request_register_link` or `/auth/request_link`).

Extract the token from the `token` query parameter of the magic link redirect URI
and POST it here. Expired or already-used tokens return HTTP 401. If the app has
disabled passwordless authentication the request returns HTTP 403. Rate-limited to
10 requests per IP per minute — exceeding this returns HTTP 429.

## Request body

- object
  - `token` string — Single-use magic link token extracted from the redirect URI query parameter.

## 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
- `403` — Passwordless login is not enabled for this organization
- `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)