# Authentication & API keys

> Authenticate with a Bearer API key, pick permissions, and restrict keys to audiences.

Source: https://www.mailmanny.com/docs/authentication
All docs for AI agents: https://www.mailmanny.com/llms.txt

Every request carries an API key in the Authorization header. Keys belong to a workspace, carry a set of permissions, and can be limited to specific audiences.

## Send the key as a Bearer token

**curl**

```bash
curl https://www.mailmanny.com/api/v1/audiences \
  -H "Authorization: Bearer $MAILMANNY_API_KEY"
```

**Node.js SDK**

```ts
import { Mailmanny } from "mailmanny";

// Reads MAILMANNY_API_KEY when you don't pass a key.
const mm = new Mailmanny(process.env.MAILMANNY_API_KEY);
```

Keys look like `mm_live_` followed by 32 letters and digits. Mailmanny stores only a hash of each key, so it can show you the full key once, when you create it. After that the list shows its first characters (`mm_live_8fK2mQ9x…`) and when it was last used.

> **Warning:** Keys are server-side secrets
> The API only accepts server-to-server requests. Calls from a web page are refused with `browser_request_blocked`, so a key in front-end code can't be used from there, but anyone who reads your bundle can still copy it. Keep keys in environment variables on your server. To collect signups in the browser, use a [hosted signup form](https://www.mailmanny.com/audience/forms) or post to your own backend, which then calls Mailmanny.

## Permissions

Pick only what the key needs. A request the key isn't allowed to make fails with 403 `restricted_api_key`.

- `full` (Full access): Everything below, plus reading any email, skipping double opt-in with a consent record and erasing contacts.
- `contacts:read` (Read contacts): List and look up contacts in your audiences.
- `contacts:write` (Add & update contacts): Add, update, tag, unsubscribe and archive contacts.
- `emails:send` (Send emails): Send transactional email and check the status of emails sent with this key.
- `templates:read` (Read templates): List and fetch your saved templates.
- `templates:write` (Push templates): Create, update and delete templates (used by mailmanny templates push).
- `events:write` (Track events): Send custom events that start API-event automations.

`templates:write` includes `templates:read`. Listing audiences (`GET /audiences`) works with any of `contacts:read`, `contacts:write` or `events:write`, so integrations can look up the audience they write to.

**403 Forbidden**

```json
{
  "statusCode": 403,
  "name": "restricted_api_key",
  "message": "This API key can't do that. It needs the \"contacts:read\" (read contacts) permission. Create a key with it in Settings → API keys."
}
```

### Presets

The create dialog offers three starting points:

- **Full access** (full): For your own backend. Can do everything.
- **Audience key** (contacts:write): Adds and updates people in the audiences you pick. Can't read your list, send email or erase anyone.
- **Sending only** (emails:send): Sends transactional email. Can't read or change contacts.

## Audience keys

Like Mailchimp's audience-level keys, a key can be limited to one or more audiences. It then only sees those audiences: listing returns just them, and any other audience id answers 404 `not_found`, exactly as if it didn't exist. Combined with the `contacts:write` permission alone, that gives you a key that can add and update people in your newsletter but can't read the list, send email or erase anyone, which is the right key for signup plugins, Zapier-style tools and contractors.

Audience restrictions apply to contacts, tags and events. Sending email isn't tied to an audience, so a sending key works across the workspace.

## Rotate and revoke keys

1. Create a new key with the same permissions.
2. Deploy it to your servers.
3. Watch the old key's **Last used** time in [Settings → API keys](https://www.mailmanny.com/settings/api-keys) stop moving, then revoke it.

Revoking is immediate and permanent: the next request with that key fails with 401 `invalid_api_key`. If a key leaks, revoke it first and rotate second. Only workspace owners and admins can create or revoke keys; a workspace can have up to 50 active keys.

## Authentication errors

- `missing_api_key` (401): No Authorization header.
- `invalid_api_key` (401): The key is malformed, unknown or revoked.
- `restricted_api_key` (403): The key lacks the permission this endpoint needs.
- `browser_request_blocked` (403): The request came from a web page. Call the API from your server.