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

# Authentication

> Create an API key and send it with every request to the REST API or the MCP server, or sign in to the MCP server with OAuth.

Every call to the REST API is authenticated with an API key. The MCP server takes the same keys, and also lets you [sign in with OAuth](https://docs.alpacarelay.com/developers/mcp/connect.md#sign-in) instead.

An API key belongs to one workspace. It acts as the owner who created it, and anything generated with it is billed to that workspace's credits.

## Create a key

**1. Open API keys**

Click your workspace name, then **Settings** → **API keys**.

**2. Create it**

Click **Create API key** and give it a name. The name is only for your own reference later — `Production backend`, `Ivan's laptop`, whatever helps you recognise it when deciding what to revoke.

**3. Copy it now**

The key is shown **once**, on the **Save your API key** screen. Copy it before closing the dialog.

> [!WARNING]
>
> **API keys is owner-only.** If you don't see it in Settings, you're not a workspace owner. To use the MCP server, [sign in with OAuth](https://docs.alpacarelay.com/developers/mcp/connect.md#sign-in), which works for any member. For the REST API, ask an owner to create a key.

> [!NOTE]
>
> There's no way to retrieve a key after that dialog closes. Only a prefix is stored for display, so the list can show you which key is which without being able to reveal any of them. Lost a key? Delete it and create another.

## Send it with a request

Pass the key as a bearer token:

```bash theme={null}
curl https://app.alpacarelay.com/api/v1/emails \
  -H "Authorization: Bearer ar_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"A welcome email for new subscribers"}'
```

Two alternative headers are accepted if a bearer token is awkward in your stack:

| Header | Example |
| - | - |
| `Authorization` | `Bearer ar_live_…` |
| `x-api-key` | `ar_live_…` |
| `apikey` | `ar_live_…` |

All three are equivalent. `Authorization` is checked first.

## Manage keys

The list shows each key's name, when it was created, and when it was last used — or **Never used**, which is the quickest way to spot a key you can safely remove.

You can create as many keys as you like. Separate keys per environment or per service are worth the small effort: revoking one doesn't disturb the others, and "last used" then tells you something specific.

> [!TIP]
>
> Minting extra keys doesn't buy extra generation throughput. Each key has its own 60-calls-a-minute budget, but the three-generation limit counts across every key in the workspace, so a second key won't let you run more generations at once. See [Credits and limits](https://docs.alpacarelay.com/developers/limits.md).

**Delete** revokes a key immediately. Calls using it start failing with `invalid_api_key` on the next request; there's no grace period.

A key also stops working when the owner who created it **leaves the workspace**. Calls then fail with `key_not_scoped`. Before removing a member who created keys, replace their keys with new ones.

## Keep keys secret

A key reaches your whole workspace. Over the [MCP server](https://docs.alpacarelay.com/developers/mcp/introduction.md#security), any key can read contacts, campaigns, and analytics, add contacts, and edit and delete emails, as well as spend credits. That includes a key you created only for REST generation. Treat it like a password:

* Keep it server-side. Never ship it in a browser bundle, a mobile app, or a public repository.
* Put it in an environment variable rather than in source.
* Rotate by creating the new key first, deploying it, then deleting the old one — that way there's no window where calls fail.

> [!WARNING]
>
> If a key leaks, delete it in **Settings** → **API keys** straight away. Until you do, anyone holding it can read and change your workspace through the MCP tools and generate emails against your credit balance.

## Errors

| Code | Status | Meaning |
| - | - | - |
| `missing_api_key` | 401 | No key in any of the accepted headers |
| `invalid_api_key` | 401 | The key doesn't exist or has been deleted |
| `key_not_scoped` | 403 | The key isn't attached to a workspace, or the owner who created it has left that workspace |
| `rate_limited` | 429 | The key has used its 60 calls for this minute |

Full list on the [Errors](https://docs.alpacarelay.com/developers/errors.md) page.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.