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

# Authentication

> How to authenticate requests to the Evermuse Ingestion API.

All requests to the Evermuse Ingestion API must be authenticated using a workspace-scoped API key.

## API Keys

API keys are scoped to a workspace and prefixed with `em_sk_` for easy identification. Each workspace can have up to 10 API keys.

### Creating an API Key

Navigate to **Settings > API Keys** in your workspace sidebar to view and manage your keys.

<Frame caption="The API Keys page lists all existing keys with their permissions, creation date, and last used date.">
  <img src="https://mintcdn.com/evermuse/vemGUR1Q1H4K7tq7/images/api-key-list-light.png?fit=max&auto=format&n=vemGUR1Q1H4K7tq7&q=85&s=f3742f33f93009bc82feacc027f01934" alt="API Keys list page" className="block dark:hidden" width="2984" height="1200" data-path="images/api-key-list-light.png" />

  <img src="https://mintcdn.com/evermuse/vemGUR1Q1H4K7tq7/images/api-key-list-dark.png?fit=max&auto=format&n=vemGUR1Q1H4K7tq7&q=85&s=aa66e2baae030176a51a7149d6b6e6d0" alt="API Keys list page" className="hidden dark:block" width="2984" height="1200" data-path="images/api-key-list-dark.png" />
</Frame>

Click **Create API Key** to open the creation dialog. Fill in the following:

* **Label** — A descriptive name for the key (e.g., "Production Ingestion Key").
* **Permissions** — Select at least one permission. To use the Ingestion API, you must enable **API Write** (`api:write`).

<Frame caption="Select the API Write permission to allow the key to send data to the Ingestion API.">
  <img src="https://mintcdn.com/evermuse/vemGUR1Q1H4K7tq7/images/api-key-create-light.png?fit=max&auto=format&n=vemGUR1Q1H4K7tq7&q=85&s=b7757de692d61f82a9687300d87b4e08" alt="Create API Key dialog" className="block dark:hidden" width="898" height="740" data-path="images/api-key-create-light.png" />

  <img src="https://mintcdn.com/evermuse/vemGUR1Q1H4K7tq7/images/api-key-create-dark.png?fit=max&auto=format&n=vemGUR1Q1H4K7tq7&q=85&s=dc455c92752b5465e34ca352d00d5705" alt="Create API Key dialog" className="hidden dark:block" width="900" height="740" data-path="images/api-key-create-dark.png" />
</Frame>

After clicking **Generate**, your API key will be displayed once. Copy it immediately — you will not be able to see it again.

<Frame caption="Copy your API key now. It cannot be retrieved after closing this dialog.">
  <img src="https://mintcdn.com/evermuse/vemGUR1Q1H4K7tq7/images/api-key-copy-light.png?fit=max&auto=format&n=vemGUR1Q1H4K7tq7&q=85&s=ce5da8c02563c87d4648f00d830eb1f7" alt="Copy API Key dialog" className="block dark:hidden" width="1030" height="548" data-path="images/api-key-copy-light.png" />

  <img src="https://mintcdn.com/evermuse/vemGUR1Q1H4K7tq7/images/api-key-copy-dark.png?fit=max&auto=format&n=vemGUR1Q1H4K7tq7&q=85&s=cb9fb3bef85a198e8554d5f546245351" alt="Copy API Key dialog" className="hidden dark:block" width="1024" height="540" data-path="images/api-key-copy-dark.png" />
</Frame>

### Permissions

API keys support the following permissions:

| Permission  | Description                                                        |
| ----------- | ------------------------------------------------------------------ |
| `api:read`  | Read access to API endpoints (e.g., checking batch status).        |
| `api:write` | Write access to API endpoints. **Required for the Ingestion API.** |
| `mcp:read`  | Read access via MCP. Requires a default product.                   |
| `mcp:write` | Write access via MCP. Requires a default product.                  |

<Note>
  The Ingestion API requires the **`api:write`** permission. Keys with only `api:read` will receive a `403 Forbidden`
  response when sending data.
</Note>

### Sending Your API Key

Include your API key in the `x-api-key` header of every request:

```bash theme={null}
curl -X POST https://api.evermuse.com/api/v1/ingest \
  -H "Content-Type: application/json" \
  -H "x-api-key: em_sk_your_api_key" \
  -d '{ ... }'
```

### Security Best Practices

* **Never expose API keys in client-side code.** API keys should only be used in server-to-server communication.
* **Rotate keys regularly.** If you suspect a key has been compromised, revoke it immediately and generate a new one.
* **Use environment variables** to store API keys rather than hardcoding them in your application.

## Error Responses

| Status Code | Description                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| `401`       | Missing or invalid API key.                                                                            |
| `403`       | API key does not have permission for the requested operation. Ensure your key has `api:write` enabled. |
| `429`       | Rate limit exceeded. Check the `retryAfter` field in the response body.                                |