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

# Authentication and scopes

> Give each integration only the access it needs.

Authenticate REST API, CLI and local MCP requests with an expiring Emailx API key. Workspace owners and admins create keys in Emailx under **Settings > API keys**.

```http theme={null}
Authorization: Bearer <EMAILX_API_KEY>
```

Use an `ex_test_` key for staging and an `ex_live_` key only on its enabled production deployment. Provider credentials and browser cookies are not API credentials.

## Available scopes

| Scope | Access |
| - | - |
| `workspaces:read` | Identity and workspace discovery |
| `agency:read` | Client access, together with the resource scope |
| `contacts:read` | Contact profiles and email lookup |
| `contacts:write` | Create, update and suppress contacts |
| `campaigns:read` | Campaigns, steps and prospects |
| `campaigns:configure` | Configure inactive drafts using a fresh revision; no generation or activation |
| `campaigns:write` | Drafts, audience attachment and pause |
| `inbox:read` | Saved reply conversations |
| `senders:read` | Stored sender metadata |
| `team:read` | Active teammates and reply-notification owner options; newly issued grants only |
| `analytics:read` | All-time totals and recorded outcomes |

Scopes restrict actions. Workspace grants restrict records. Your current role can restrict both: viewers cannot write, and revoked agency assignments lose access even if the key still contains a client grant. Archived or pending-deletion workspaces are inaccessible.

## Create a key

1. In Emailx, open your profile menu and choose **API keys**. Owners and admins see **New API key**; members and viewers cannot create keys.
2. Give the key a name that says where it is used, such as "CRM sync".
3. Choose the workspaces it may use. Agency owners and admins can also choose client workspaces.
4. Choose the permissions. Start with **Read only** and add only what the integration needs.
5. Choose when it expires: 30, 90 or 180 days, or one year.
6. Copy the key from the next screen. Emailx shows it once and stores only a fingerprint of it.

A key can never do more than the person who created it. If that person loses access to a workspace, or leaves the team, their keys stop working there immediately.

## Rotate or revoke

To rotate, create a new key, update your secret store, check that `/me` works with the new key, then revoke the old one. To revoke, open **Settings > API keys**, use the row's menu and choose **Revoke**. A revoked key stops working at once, including for background jobs that have not started.

## Keep secrets out of clients

Make REST requests on your backend. The API does not grant cross-origin browser access. Keep keys out of page code, URLs and analytics. For local CLI/MCP, use a [private key file](https://docs.emailx.ai/en/cli/authentication.md). Share `X-Request-Id` with support instead of authorization headers.


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