---
title: Auth
description: Authenticate users and obtain access tokens.
---

# Auth

Authenticate users and obtain access tokens.

## [POST /auth/email/start](/api-reference/auth#tag/auth/POST/auth/email/start)

Start email login

Initiates an email-based login flow by sending a verification code to the provided email address.

The response includes a nonce that must be used when verifying the login, along with timing information for the verification code.

This endpoint always returns 202 Accepted to prevent email enumeration attacks.

Authentication: Public

### Request body (required)

Type: `object`

- `email` (`string`, required, email, example john.doe@example.com) — The email address to send the verification code to.

### Responses

#### 202

Login flow initiated. A verification code has been sent to the email address if it exists in the system.

Type: [StartEmailLoginResponse](/api-reference/models.md#models/StartEmailLoginResponse)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 429

Too many requests have been sent in a given amount of time.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
curl https://apiv2.example.com/api/v2/auth/email/start \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "john.doe@example.com"
}'
```

## [POST /auth/email/verify](/api-reference/auth#tag/auth/POST/auth/email/verify)

Verify email login

Verifies an email login by validating the verification code sent to the email address.

On success, returns an OAuth2-compatible token response with:
- `accessToken`: JWT token for authenticating subsequent API requests
- `tokenType`: Always "Bearer"
- `expiresIn`: Token lifetime in seconds
- `userId`: The authenticated user's identifier

Use the access token in the Authorization header: `Authorization: Bearer {accessToken}`

Authentication: Public

### Request body (required)

Type: `object`

- `email` (`string`, required, email, example john.doe@example.com) — The email address used to initiate the login.
- `nonce` (`string`, required, example a1b2c3d4-e5f6-7890-abcd-ef1234567890) — The nonce returned from the start login request.
- `code` (`string`, required, pattern ^[0-9]{6}$, example 123456) — The 6-digit verification code sent to the email address.

### Responses

#### 200

Login verified successfully. Returns access token for API authentication.

Type: [TokenResponse](/api-reference/models.md#models/TokenResponse)

#### 400

The request was malformed or invalid.

Type: [Error](/api-reference/models.md#models/Error)

#### 401

Authentication is required to access this resource.

Type: [Error](/api-reference/models.md#models/Error)

#### 429

Too many requests have been sent in a given amount of time.

Type: [Error](/api-reference/models.md#models/Error)

#### 500

An unexpected error occurred on the server.

Type: [Error](/api-reference/models.md#models/Error)

### Example request

```bash
curl https://apiv2.example.com/api/v2/auth/email/verify \
  --request POST \
  --header 'Content-Type: application/json' \
  --data '{
  "email": "john.doe@example.com",
  "nonce": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "code": "123456"
}'
```