---
title: "Sign in with a magic link or code"
method: POST
path: "/accounts/auth-with-magic-link"
tags: ["Client Access"]
---

# Sign in with a magic link or code

`POST /accounts/auth-with-magic-link`

## Request

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

Signs a client in with a single-use magic-link `token`, or with the 6-digit `code` together with `email` and `account`. Repeated wrong codes lock the sign-in until an admin clears it (see **/accounts/clear-client-signin-lock**).

## Request body

- object
  - `token` string: Single-use token from the link
  - `code` string: 6-digit code from the invitation email
  - `email` string: Email address of the client user
  - `account` string: Account name; required with `code`

## Response `200`

Success

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

## Other responses

- `400`: Bad request
- `429`: Sign-in code locked after too many attempts

## Changes

- **2026-11-12** `700eb1ace61a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/quivaworks/apis/quiva-ai-gateway/changes/accounts/auth-with-magic-link/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)