---
title: "Authenticate with password"
method: POST
path: "/accounts/auth-with-password"
tags: ["Authentication"]
---

# Authenticate with password

`POST /accounts/auth-with-password`

## Request

- Base URL: `https://api.quiva.ai`
- URL: `https://api.quiva.ai/accounts/auth-with-password`
- Auth: none required
- TypeScript: <https://skmtc.dev/quivaworks/apis/quiva-ai-gateway/docs/accounts/auth-with-password/post.ts> (a function with typed inputs; its response is checked against the schema)

Authenticates a user with email and password. Depending on the user, the response is one of: tokens (`AuthResponse`), an MFA token when TOTP is on and the device is not remembered (`MfaRequiredResponse`), or an account picker (`AccountSelectResponse`) when no `account` was given and the user belongs to several accounts. Send `device_token` from an earlier MFA sign-in to skip TOTP.

## Request body

- AuthWithPasswordRequest
  - `account` string: Account name or sign-in slug (optional). If it is omitted and the user belongs to several accounts, the response asks the caller to pick one (`select_account`).
  - `email` string, email, required: User's email address
  - `password` string, password, required: User's password
  - `device_token` string: Remembered-device token from an earlier MFA sign-in (valid for 30 days). A valid token skips the TOTP step.

## Response `200`

Authentication successful or MFA required

- object
  - `data` union, required
    - AuthResponse: Tokens and the signed-in user and account.
      - `refresh_token` string: Refresh token
      - `auth_token` string: Authentication token (JWT)
      - `passkey_enabled` boolean
      - `totp_enabled` boolean
      - `first_sign_in` boolean: True on the first sign-in after an invitation; the app routes it to MFA setup
      - `account` AccountPublicInfo
        - `name` string: Account name (normalized)
        - `id` string: Account unique identifier - 10 digits
        - `display_name` string: Account display name
        - `root_email` string, email: Root user email address
        - `subscription_status` 'active' | 'pending' | 'cancelled': Subscription status
        - `subscription_plan` string: Subscription plan
        - `emergency_credit` number, float: Emergency credit amount
        - `country` string: Country
        - `company_name` string: Company name
        - `address` string: Address
        - `website` string: Website
        - `phone_number` string: Phone number
        - `scheduled_for_deletion` boolean: Whether the account is scheduled for deletion
        - `deletion_date` string, date-time: If the account is scheduled for deletion, it will be deleted on this date
        - `region` string: Region
        - `provider` string: Provider
        - `bstier` integer: BS tier
        - `cloud` boolean: Cloud functionality enabled. It true, the user has access to quiva.ai Cloud
        - `hub` boolean: Hub functionality enabled. It true, the user has access to quiva.ai Hub
      - `user` string, email: User email
      - `user_id` string
      - `first_name` string
      - `last_name` string
      - `role` string: Role on the signed-in account
      - `mfa` MfaInfo
        - `passkey_enabled` boolean, required: Whether passkey authentication is enabled
        - `totp_enabled` boolean, required: Whether TOTP authentication is enabled
      - `theme` string
      - `sound` boolean
      - `advanced_mode` boolean
      - `voice_transcription` boolean
      - `onboarding_progress` object
      - `timezone` string
      - `notification_preferences` object
      - `folder` string: Set for client users filed under a folder
      - `device_token` string: Present when `remember_device` was set on an MFA step. Send it as `device_token` on later password sign-ins.
    - MfaRequiredResponse
      - `token` string: MFA token. Use it with the TOTP, recovery-code or passkey authentication request.
      - `passkey_enabled` boolean: Whether passkey authentication is enabled
      - `totp_enabled` boolean: Whether TOTP authentication is enabled
    - AccountSelectResponse: Returned instead of tokens when an email-only sign-in matches several accounts. Pass `token` and the chosen account id to `POST /accounts/auth-select-account`.
      - `select_account` true, required
      - `accounts` LoginAccount[], required
        - `id` string, required
        - `name` string, required: Account name (sign-in key)
        - `display_name` string
        - `role` string, required: The user's role on that account
        - `invitation_pending` boolean
      - `token` string, required: Single-use token that names the user. Spent when the pick is valid.

## Other responses

- `401`: Authentication failed

## Changes

- **2026-11-12** `700eb1ace61a`: 1 breaking, 18 info
  - added `#/components/schemas/AccountSelectResponse` to the `data` response property `oneOf` list for the response status `200`
  - added the new optional request property `device_token`
  - added the optional property `data/oneOf[#/components/schemas/AuthResponse]/account` to the response with the `200` status
  - added the optional property `data/oneOf[#/components/schemas/AuthResponse]/advanced_mode` to the response with the `200` status
  - …15 more
- **2025-06-12** `4979dfd00eda`: 1 breaking, 2 info
  - the response's body type changed from no type to `object` for status `200`
  - removed `#/components/schemas/AuthResponse, #/components/schemas/MfaRequiredResponse` from the response body `oneOf` list for the response status `200`
  - added the required property `data` to the response with the `200` status

[Operation history](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway/changes/accounts/auth-with-password/post.md)

---

[API](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway.md) - [All operations](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway/llms.txt) - [OpenAPI document](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway/revisions/700eb1ace61a?raw)