---
title: "Authenticate with email and password"
method: POST
path: "/api/v1/auth/login"
tags: ["auth"]
---

# Authenticate with email and password

`POST /api/v1/auth/login`

Authenticates a user with an email address and password and returns a short-lived
access token, a refresh token, and the authenticated user object. Use the refresh
token with the `/auth/refresh` endpoint to obtain new access tokens without
re-authenticating.

Password login must be enabled for the app; apps that have disabled password
authentication return HTTP 403. Requests are rate-limited per IP (10 per minute)
and per email-IP pair (5 per minute) — exceeding either limit returns HTTP 429.

## Request body

- object
  - `email` string, required — Email address of the user to authenticate.
  - `password` string, required — Password for the account associated with the given email.

## 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 credentials
- `403` — Password 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)