> ## Documentation Index
> Fetch the complete documentation index at: https://docs.12m.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Bearer tokens, scoped per org, identity in the URL.

Every request needs an org-scoped API key in the `Authorization`
header.

```http theme={null}
Authorization: Bearer sk_live_8f322095d848...
```

## Keys are org-scoped

A key authorizes acting as **any identity in your org**. The specific
identity is always identified by handle in the URL:

```
/v1/identities/alice.acme@inboxbase.ai/send
/v1/identities/morgan.acme@inboxbase.ai/send
```

The same key can target both. Per-request identity routing is part of the
URL, never the header.

<Note>
  If you need stricter isolation — e.g. a key that can only act on one
  identity — that's on the roadmap as scoped keys. Today the right shape
  is one org per isolated tenant.
</Note>

## Minting a key

From the dashboard at [inboxbase.ai/app/developers](https://inboxbase.ai/app/developers):

1. **Create key** — name it (audit-log only; the customer never sees
   the name).
2. **Copy the value** — shown once, starts with `sk_live_`. Store it in
   a secret manager.
3. **Revoke** anytime from the same page. Revocation is immediate.

The dashboard shows the prefix (`sk_live_8f32…`) and the creation
timestamp for every active key, so you can identify which one a leaked
prefix corresponds to.

## URL-encoding the handle

Handles look like email addresses (`alice.acme@inboxbase.ai`). The `@` and
`.` characters are valid in URL paths per RFC 3986, but
`encodeURIComponent` is recommended for safety, especially if you're
constructing URLs from user-controlled handle values.

```js theme={null}
const handle = "alice.acme@inboxbase.ai";
const url = `https://api.inboxbase.ai/v1/identities/${encodeURIComponent(handle)}/send`;
```

## Errors

<ResponseField name="401 missing api key">
  No `Authorization` header on the request.
</ResponseField>

<ResponseField name="401 invalid api key format">
  Header present but value doesn't start with `sk_`.
</ResponseField>

<ResponseField name="401 invalid api key">
  Key not found, expired, or revoked. The key may have been deleted
  from the dashboard, or rotated and the old value was reused.
</ResponseField>

<ResponseField name="404 identity not found in org">
  Key is valid, but the identity handle in the URL doesn't belong to the
  key's org. Most often this is a typo in the handle or a copy-paste
  from a different environment.
</ResponseField>