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

# Authentication

# Authentication

All API requests must include a valid API key in the `X-API-Key` header.

```bash theme={null}
curl -H "X-API-Key: bme_abc123def456ghi789jkl012mno345pqr678stu90v" \
  https://api-us1-1.benchmarkemail.com/api/contact-structure
```

## Getting an API Key

1. Log in to Benchmark Email with an **Owner** account. Only users with the Owner role can create and manage API keys.
2. Navigate to **Settings > API Keys**.
3. Click **Create API Key**.
4. Enter a descriptive name (e.g., "Zapier Sync", "CRM Integration").
5. Select the scopes (permissions) the key needs -- see [Scopes](#scopes) below.
6. Optionally set an expiration date. If you skip this, the key never expires.
7. Click **Create** and copy the key immediately.

The full API key is displayed **only once** at creation time. If you lose it, you can regenerate the key from the API Keys page (this invalidates the old key and issues a new one).

## API Key Format

All Benchmark Email API keys start with the `bme_` prefix, followed by 43 random characters:

```
bme_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v
```

Total length: 47 characters (4-character prefix + 43 random characters).

## Scopes

Each API key is granted one or more scopes that control which resources it can access. Scopes follow the `{resource}:{access}` format.

### Available Scopes

| Scope             | Description                                                                                                 |
| ----------------- | ----------------------------------------------------------------------------------------------------------- |
| `contacts:read`   | Read contacts, lists, contact structures, search contacts, export contacts, view contact events and history |
| `contacts:write`  | Create, update, and delete contacts and lists; update contact structures                                    |
| `campaigns:read`  | Read campaigns and browse email templates                                                                   |
| `campaigns:write` | Create, update, delete, and duplicate campaigns                                                             |
| `reports:read`    | View dashboard summaries and email performance reports                                                      |
| `domains:read`    | View email sending domains                                                                                  |

### Write Implies Read

Granting **write** access for a resource automatically includes **read** access. For example, a key with `contacts:write` can also read contacts -- you do not need to select both.

### Principle of Least Privilege

Create keys with only the permissions they need. For example:

* A reporting dashboard only needs `reports:read`.
* A contact sync integration needs `contacts:write` (which includes read access).
* A read-only data export tool needs `contacts:read`.

### Scope Errors

If a request requires a scope that your key does not have, you will receive a `403 Forbidden` response with a message identifying the required scope. See [Errors](./errors.md#missing-required-scope-403) for details.

## Account Standing

API keys only work when your Benchmark Email account is in good standing. Keys are active when your account status is:

* **Open** -- normal active account
* **Pending Cancel** -- account is scheduled for cancellation but still active

Keys will stop working (returning `403 Forbidden`) if your account is in any other status, such as suspended, past due, or terminated.

## Key Lifecycle

| Key State    | Behavior                                                          |
| ------------ | ----------------------------------------------------------------- |
| **Active**   | Key authenticates requests normally                               |
| **Inactive** | Key has been deactivated by the owner; returns `401 Unauthorized` |
| **Expired**  | Key's expiration date has passed; returns `401 Unauthorized`      |
| **Deleted**  | Key has been permanently removed; returns `401 Unauthorized`      |

You can deactivate and reactivate keys from the API Keys page without deleting them. This is useful for temporarily disabling an integration.

## Example: Listing Contact Structures

```bash theme={null}
curl -X GET \
  -H "X-API-Key: bme_abc123def456ghi789jkl012mno345pqr678stu90v" \
  https://api-us1-1.benchmarkemail.com/api/contact-structure
```

**Response (200 OK):**

```json theme={null}
[
  {
    "_id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "label": "Default Contacts",
    "keyName": "Email",
    "keyType": "email",
    "fields": [
      { "_id": "64a1b2c3d4e5f6a7b8c9d100", "label": "First Name", "dataType": "text" },
      { "_id": "64a1b2c3d4e5f6a7b8c9d101", "label": "Last Name", "dataType": "text" }
    ]
  }
]
```

## Example: Creating a Contact

```bash theme={null}
curl -X POST \
  -H "X-API-Key: bme_abc123def456ghi789jkl012mno345pqr678stu90v" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "john.smith@example.com",
    "contactStructureId": "64a1b2c3d4e5f6a7b8c9d0e1",
    "fields": [
      { "_id": "64a1b2c3d4e5f6a7b8c9d100", "value": "John" },
      { "_id": "64a1b2c3d4e5f6a7b8c9d101", "value": "Smith" }
    ]
  }' \
  https://api-us1-1.benchmarkemail.com/api/contact
```

**Response (200 OK):**

```json theme={null}
{
  "_id": "65a1b2c3d4e5f6a7b8c9d0e2",
  "key": "john.smith@example.com",
  "contactStructureId": "64a1b2c3d4e5f6a7b8c9d0e1",
  "fields": [
    { "_id": "64a1b2c3d4e5f6a7b8c9d100", "value": "John" },
    { "_id": "64a1b2c3d4e5f6a7b8c9d101", "value": "Smith" }
  ],
  "status": { "primary": "active", "secondary": "confirmed" },
  "createdAt": "2026-03-30T14:22:00.000Z"
}
```

This request requires the `contacts:write` scope. If your key only has `contacts:read`, you will receive a `403 Forbidden` error.

## Next Steps

* [Rate Limits](./rate-limits.md) -- understand request limits and quotas
* [Errors](./errors.md) -- handle error responses
* [API Reference](./README.md) -- explore available resources