# Authentication (/authentication)

Every request needs an API key, sent as a Bearer token in the `Authorization` header:

```bash
curl "https://app.alienmail.io/api/v1/campaigns" \
  -H "Authorization: Bearer $ALIENMAIL_API_KEY"
```

There is no sign-in step and no token to refresh: send the key itself on each request.

## API keys [#api-keys]

Create keys in **Workspace settings → Integrations**, under **API keys**. Each key has:

- **A name**, so you know which system uses it. Names are unique in a workspace.
- **A role**, which decides what the key may do.

The full key is shown once, when it is created. Alienmail keeps only a hash, so a lost key can't be shown again: create a new one and delete the old one. The key list shows when each key was last used. A workspace can create up to 10 keys a day.

A key belongs to **one workspace**. It only sees and changes that workspace's campaigns, leads and mailboxes, which is why API paths have no workspace id. To work with several workspaces, create a key in each.

<Callout type="warn" title="Keep keys secret">
A key acts for your workspace. Store it in your server's secrets, never in browser or mobile code, and delete it right away if it leaks.
</Callout>

## Roles and permissions [#roles-and-permissions]

When you create a key you pick its role:

| Role | What the key can do |
|---|---|
| **Read-Only API Key** | Read: list campaigns, leads and mailboxes. |
| **Write Access Key** | Everything in this API: read, start and pause campaigns, add, update and remove leads, update mailboxes. |

A role is a set of permissions, and each endpoint needs one of them. A request to an endpoint whose permission the role lacks gets `403 forbidden`, and the message names the missing permission.

| Permission | Endpoints | Read-Only | Write Access |
|---|---|---|---|
| `CAMPAIGN_READ` | [List campaigns](/api-reference/campaigns/listCampaigns), [List leads](/api-reference/leads/listLeads) | Yes | Yes |
| `CAMPAIGN_START` | [Start or resume a campaign](/api-reference/campaigns/startCampaign) | No | Yes |
| `CAMPAIGN_STATUS_UPDATE` | [Pause a campaign](/api-reference/campaigns/pauseCampaign) | No | Yes |
| `LEAD_CAMPAIGN_ENROLL` | [Add leads](/api-reference/leads/addLeads), [Update a lead](/api-reference/leads/updateLead), [Remove a lead](/api-reference/leads/removeLead), [Remove leads](/api-reference/leads/removeLeads) | No | Yes |
| `SMTP_READ` | [List mailboxes](/api-reference/mailboxes/listMailboxes) | Yes | Yes |
| `SMTP_UPDATE` | [Update a mailbox](/api-reference/mailboxes/updateMailbox) | No | Yes |

Pick the role with the least access that covers what your integration does: a dashboard that only reads needs Read-Only, a CRM sync needs Write Access.

## When a key stops working [#when-a-key-stops-working]

A key answers `401 unauthorized` when:

- it was deleted (revoked) in **Workspace settings → Integrations**;
- the person who created it left the workspace, or their account was deleted or suspended;
- the workspace was archived or deleted.

The answer is the same for all of them, and for a key that never existed.

## Errors [#errors]

| Status | Code | Why |
|---|---|---|
| `401` | `unauthorized` | The `Authorization` header is missing or not `Bearer <key>`, or the key doesn't work (see above). |
| `403` | `forbidden` | The key's role lacks the permission the endpoint needs. |
| `429` | `rate_limited` | Too many requests with this key. See [Rate limits](/rate-limits). |

```json
{ "error": { "code": "forbidden", "message": "This API key's role does not allow this request. It needs the CAMPAIGN_START permission." } }
```

## The Alienmail MCP server uses the same keys [#the-alienmail-mcp-server-uses-the-same-keys]

The [Alienmail MCP server](/guides/mcp-server) accepts the same API keys, with the same roles. AI tools that support OAuth can instead sign in with your Alienmail account and act in one workspace with your role, without a key (see [Connect by signing in](/guides/mcp-server#connect-by-signing-in)). To build that sign-in into your own app, see [Connect your own app](/guides/mcp-oauth).

OAuth is for the MCP server only. The REST API on this site takes API keys.