---
title: "Auth API"
description: "Auth in the OneSend API: 10 endpoints. Dashboard accounts and session tokens."
url: https://onesend.email/docs/api-reference/auth/
---
[Docs](https://onesend.email/docs/) / [API reference](https://onesend.email/docs/api-reference/)

# Auth

Dashboard accounts and session tokens.

Base URL `https://your-server.example` (your OneSend server). [Authentication](https://onesend.email/docs/api-reference/#authentication) and errors are described in the [overview](https://onesend.email/docs/api-reference/).

## Create an account

POST `/v1/auth/signup`

The first account on a fresh instance becomes the owner. Afterwards signup follows `ONESEND_SIGNUP`. Sets the `onesend_session` HttpOnly cookie for the dashboard and returns the session `token` for scripts.

**Authentication:** None.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `email`required | `string (email)` |  |
| `password`required | `string` |  |
| `name` | `string` |  |
| `workspaceName` | `string` |  |
| `setupCode` | `string` | The setup code printed by the installer (ONESEND\_SETUP\_CODE). Needed only for the first account, when the server has one. |

### Responses

`201` Success

```
{
  "token": string,
  "user": {
    "id": string,
    "email": string,
    "name": string or null
  },
  "workspace": {
    "id": string,
    "name": string,
    "slug": string,
    "plan": string
  }
}
```

**Errors: 400, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Sign in

POST `/v1/auth/login`

Sets the `onesend_session` HttpOnly cookie for the dashboard and returns the session `token` for scripts. Rate limited per client and per account. Accounts with two-factor authentication get 401 `mfa_required` with `error.details.mfaToken`; finish with POST /v1/auth/login/2fa.

**Authentication:** None.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `email`required | `string (email)` |  |
| `password`required | `string` |  |

### Responses

`200` Success

```
{
  "token": string,
  "user": {
    "id": string,
    "email": string,
    "name": string or null
  },
  "workspace": {
    "id": string,
    "name": string,
    "slug": string,
    "plan": string
  }
}
```

**Errors: 400, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Sign out (revoke the session and clear the cookie)

POST `/v1/auth/logout`

**Authentication:** None.

### Responses

`204` No content

**Errors: 400, 404, 409, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Current user, workspace and credentials

GET `/v1/auth/me`

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Responses

`200` Success

```
{
  "user": {
    "id": string,
    "email": string,
    "name": string or null
  },
  "workspace": {
    "id": string,
    "name": string,
    "slug": string,
    "plan": string,
    "settings": object
  },
  "workspaces": [{
    "id": string,
    "name": string,
    "role": string
  }],
  "auth": {
    "kind": "session" | "api_key",
    "scope": string,
    "mode": string
  },
  "role": string or null,
  "twoFactor": {
    "enabled": boolean,
    "required": boolean,
    "blocked": boolean
  },
  "capabilities": {
    "edition": "self_hosted" | "cloud" | "desktop",
    "inbox": boolean,
    "connectedAccounts": boolean,
    "encryptMail": boolean,
    "cloudLink": {
      "linked": boolean,
      "url": string,
      "workspaceName": string
    },
    "license": {
      "required": boolean,
      "active": boolean
    },
    "plansEnabled": boolean
  }
}
```

**Errors: 400, 401, 403, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Switch the current workspace

POST `/v1/auth/workspace`

Sessions only. Later requests with this session act in the chosen workspace (the dashboard workspace switcher). Scripts can also send `X-Workspace-Id` per request. API keys always belong to one workspace.

**Authentication:** `Authorization: Bearer` with an API key or a session token.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `workspaceId`required | `string` |  |

### Responses

`200` Success

```
{
  "workspace": {
    "id": string,
    "name": string,
    "slug": string,
    "plan": string
  },
  "role": string
}
```

**Errors: 400, 401, 403, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `401` Missing credentials (`unauthorized`), an unknown or revoked API key (`invalid_api_key`) or an expired session (`invalid_session`). Type `unauthorized`.
- `403` The API key's permission does not allow this operation (`insufficient_scope`; configuration needs an `admin` key), a test key was used outside its sandbox (`test_key_not_allowed`), a Conversion tracking key was used (`publishable_key`), or a cookie request is missing `X-OneSend-Client: dashboard` (`csrf_header_required`). Type `forbidden`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Sign in: second step

POST `/v1/auth/login/2fa`

When the account has two-factor authentication, sign-in answers 401 `mfa_required` with `error.details.mfaToken`; send it here with the code from the authenticator app or a recovery code. The challenge is valid for 5 minutes.

**Authentication:** None.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `mfaToken`required | `string` |  |
| `code` | `string` |  |
| `recoveryCode` | `string` |  |

### Responses

`200` Success

```
{
  "token": string,
  "user": {
    "id": string,
    "email": string,
    "name": string or null
  },
  "workspace": {
    "id": string,
    "name": string,
    "slug": string,
    "plan": string
  },
  "recoveryCodesRemaining": number
}
```

**Errors: 400, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Request a password reset link

POST `/v1/auth/password/forgot`

Always answers 202 with the same message and timing, whether or not the email has an account. The email is sent through the router of a workspace the account belongs to. If the server cannot deliver email (only the sandbox provider), an administrator can create a link on the server: `npm run admin -- reset-password <email>`.

**Authentication:** None.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `email`required | `string (email)` |  |

### Responses

`202` Success

```
{
  "ok": true,
  "message": string
}
```

**Errors: 400, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Check a password reset link

POST `/v1/auth/password/check`

Tells the reset page whether the link can still be used (and whether a two-factor code will be needed). Does not use the link.

**Authentication:** None.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `token`required | `string` |  |

### Responses

`200` Success

```
{
  "valid": boolean,
  "twoFactor": boolean
}
```

**Errors: 400, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## Set a new password with a reset link

POST `/v1/auth/password/reset`

The link works once, for 30 minutes, and stops working if the password changes in the meantime. Every session of the account is signed out. Accounts with two-factor authentication also need a code (or a recovery code). Does not sign in: sign in with the new password afterwards.

**Authentication:** None.

### Request body

application/json, required.

| Field | Type | Description |
|---|---|---|
| `token`required | `string` |  |
| `password`required | `string` |  |
| `code` | `string` | Two-factor code or recovery code, when the account has two-factor authentication |

### Responses

`200` Success

```
{
  "ok": true
}
```

**Errors: 400, 404, 409, 413, 415, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `409` The request conflicts with the current state, for example a duplicate name or a reused `Idempotency-Key` (`conflict`)
- `413` The request body is larger than the limit for this endpoint (`payload_too_large`)
- `415` The body is not sent as `Content-Type: application/json` (`unsupported_media_type`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)

## First-run status

GET `/v1/setup/status`

Whether this instance has an account yet, and how sign-up works. No authentication. The database kind is shown only until the first account exists; paths, hosts and secrets are never returned.

**Authentication:** None.

### Responses

`200` Success

```
{
  "hasUsers": boolean,
  "databaseKind": "sqlite" | "postgres" | "libsql" | "pglite" | "d1" | null,
  "dataDirIsDefault": boolean or null,
  "publicUrl": string,
  "signupMode": "open" | "first-user" | "invite" | "closed",
  "signupAllowed": boolean,
  "setupCodeRequired": boolean
}
```

**Errors: 400, 404, 429, 500**

- `400` Invalid request: validation failed, a parameter is not allowed, the body is not valid JSON (`invalid_json`) or the pagination cursor is not valid (`invalid_cursor`). Type `invalid_request`.
- `404` The resource does not exist in this workspace (`not_found`)
- `429` Too many requests; retry after the time in the `Retry-After` header (`rate_limited`)
- `500` Unexpected server error (`internal`)
