# Authentication

Base URL, bearer credentials, scope rules, and error conventions for the OpenEmail HTTP API.

Every OpenEmail operation is an HTTP call against a single base URL. The CLI and
the interactive console are clients of this API — anything they do, you can do
directly.

This page covers what every request needs, whichever endpoint it calls. For a
specific endpoint, see the API reference in its own tab above — it is generated
from the spec and covers the whole surface.

## Base URL

```
https://api.open.email
```

Every path is versioned and already includes the prefix, so a full request URL
looks like `https://api.open.email/api/v1/identities`. Examples below assume:

```bash
export API="https://api.open.email/api/v1"
```

JMAP is advertised on its own hostname, `jmap.open.email`, and is not part of
this REST contract.

## Authentication

Every request carries a bearer credential:

```bash
curl "$API/auth/whoami" -H "Authorization: Bearer $TOKEN"
```

There are two kinds, and which one you hold determines what you can reach:

| Credential | Prefix | Scope |
| --- | --- | --- |
| API key | `oek_` | The account, and every mailbox under it; or, limited to some domains, only those |
| Mailbox app password | `oemp_` | One mailbox |

A request with no credential is refused with `401 unauthorized`. A mailbox app
password used on an account-level route is refused with `403
insufficient_scope` — it is a valid credential, just not for that route. An API
key limited to some domains reaches only those domains and the mailboxes with an
address on them: account-level routes refuse it with `403
account_credentials_required`, and another domain's resources answer `404`.

Four routes need no credential at all: the health check, calendar feed and
webhook fetch URLs (where the token in the path *is* the credential), and the
public branding reads a sign-in screen needs before anyone has signed in.

### Check a credential

[`GET /auth/whoami`](/docs/api/credentials/get_AuthWhoami)

Describes the credential you are holding — useful when a call returns `403` and
you need to know what you actually authenticated as:

```json
{
  "type": "mailbox",
  "accountId": "acct_...",
  "mailboxId": "mb_...",
  "credentialId": "cred_...",
  "keyId": null
}
```

`type` is `account`, `mailbox`, or `system`. The other fields are populated
according to that type — a mailbox credential names its mailbox, an account key
does not.

### Find your mailbox's id

A mailbox app password's own mailbox is the `mailboxId` that whoami answers, and
that id is what every `{mailboxId}` path segment takes:

```bash
curl "$API/mailboxes/$MAILBOX_ID/messages" -H "Authorization: Bearer $TOKEN"
```

There is no alias for it: a path with `me` in place of the id answers `404`.

## Errors

Errors always answer with a machine-readable code:

```json
{ "error": "address_taken" }
```

Schema failures carry the offending fields alongside the code:

```json
{ "error": "validation_failed", "issues": [] }
```

Codes are `snake_case` and stable — match on `error`, not on the HTTP status or
any human-readable text, both of which are shared across several conditions.

## In the TypeScript SDK

The [TypeScript SDK](/docs/sdks/typescript) sends the credential for you, to
the API's address only, and reads `OPENEMAIL_API_KEY` when you give it none
([The client](/docs/sdks/typescript/client)).
[`auth.whoami`](/docs/sdks/typescript/auth/whoami) is `GET /auth/whoami`, and
a failed call rejects with one error type whose `code` is the API's `error`
([Errors and retries](/docs/sdks/typescript/errors)).

## Where to go next

These guides walk the flows most people need first:

- **[Mailboxes](/docs/guides/mailboxes)** — create, list, and read mailboxes.
- **[Messages](/docs/guides/messages)** — list a mailbox and read a message back.
- **[Sending](/docs/guides/sending)** — send from a mailbox, per-recipient results.

For anything else, the [API reference](/docs/api/overview) covers every
endpoint with its schemas and a runnable example per language.
