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

# Authentication

> API keys, scopes, and permissions

# Authentication

All API requests must be authenticated using an API key. API keys provide stateless, scoped authentication for programmatic access.

### Key format

| Environment | Prefix     | Example                                  |
| ----------- | ---------- | ---------------------------------------- |
| Production  | `nl_live_` | `nl_live_a1b2c3d4e5f6...` (64 hex chars) |
| Test        | `nl_test_` | `nl_test_a1b2c3d4e5f6...` (64 hex chars) |

Keys use 256-bit entropy (64 hex characters after the prefix).

### Passing your API key

You can authenticate using either method:

**Option 1: X-API-Key header (recommended)**

```bash theme={null}
curl -H "X-API-Key: nl_live_YOUR_API_KEY" \
  https://api.naturalead.ai/api/leads
```

**Option 2: Bearer token**

```bash theme={null}
curl -H "Authorization: Bearer nl_live_YOUR_API_KEY" \
  https://api.naturalead.ai/api/leads
```

<Info>
  When both `X-API-Key` and `Authorization: Bearer nl_*` are present, the `X-API-Key` header takes precedence.
</Info>

### Key security

* The full key is shown **only once** at creation. Naturalead stores only a SHA-256 hash.
* Keys are scoped to a single account (organization).
* Each key has a `keyHint` (last 4 characters) for identification in the dashboard.
* Keys can be set to expire at a specific date.

### Creating API keys

Create keys via the dashboard (**Settings > API Keys**) or programmatically:

```bash theme={null}
curl -X POST "https://api.naturalead.ai/api/api-keys" \
  -H "X-API-Key: nl_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM Integration",
    "scopes": ["leads:view", "leads:import", "leads:sync_create"],
    "environment": "live"
  }'
```

### Key lifecycle

| Action | Endpoint                         | Description                                 |
| ------ | -------------------------------- | ------------------------------------------- |
| Create | `POST /api/api-keys`             | Generate a new key with selected scopes     |
| List   | `GET /api/api-keys`              | View all keys for the account (masked)      |
| Revoke | `PATCH /api/api-keys/:id/revoke` | Disable a key (irreversible)                |
| Rotate | `POST /api/api-keys/:id/rotate`  | Revoke old key, generate new one atomically |
| Delete | `DELETE /api/api-keys/:id`       | Permanently delete a revoked key            |

## Scopes and Permissions

API keys are scoped to specific permissions. A key can only perform actions matching its scopes.

### Available scopes

| Domain        | Scope                         | Description                              |
| ------------- | ----------------------------- | ---------------------------------------- |
| Leads         | `leads:view`                  | List, search, and filter leads           |
| Leads         | `leads:import`                | Create, update, delete, and import leads |
| Leads         | `leads:start_conversation`    | Start conversations with leads           |
| Leads         | `leads:sync_create`           | Bulk sync (create/update) leads          |
| Leads         | `leads:sync_delete`           | Bulk delete synced leads                 |
| Conversations | `conversations:view`          | List and read conversations              |
| Conversations | `conversations:edit`          | Edit conversation data                   |
| Conversations | `conversations:send_message`  | Send messages in conversations           |
| Conversations | `conversations:change_status` | Update conversation status               |
| Agent Config  | `agent_config:view`           | View agent configurations                |
| Agent Config  | `agent_config:edit`           | Create and modify agents                 |
| Knowledge     | `knowledge:view`              | View knowledge bases and documents       |
| Knowledge     | `knowledge:upload`            | Upload documents and manage sources      |
| Knowledge     | `knowledge:delete`            | Delete documents and knowledge bases     |
| Campaigns     | `campaigns:view`              | List and view campaigns                  |
| Campaigns     | `campaigns:create`            | Create new campaigns                     |
| Campaigns     | `campaigns:edit`              | Update campaign settings                 |
| Campaigns     | `campaigns:launch`            | Launch and pause campaigns               |
| Campaigns     | `campaigns:delete`            | Delete campaigns                         |
| Analytics     | `analytics:view`              | View analytics and reports               |
| A/B Testing   | `ab_testing:view`             | View A/B tests                           |
| A/B Testing   | `ab_testing:manage`           | Create and manage A/B tests              |
| Audit         | `audit:view`                  | View audit logs                          |
| Audit         | `audit:export`                | Export audit logs                        |
| API Keys      | `api_keys:view`               | View API keys                            |
| API Keys      | `api_keys:manage`             | Manage API keys                          |

<Note>
  When creating an API key, you can only grant scopes that your own role has permission for. This prevents privilege escalation.
</Note>

## Error responses

| Status | Response                                                                                                         | Cause                                     |
| ------ | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| `401`  | `{"error": "Invalid or expired API key"}`                                                                        | API key is revoked, expired, or not found |
| `401`  | `{"error": "Authentication required. Provide an API key via X-API-Key header or Authorization: Bearer header."}` | No API key provided                       |
| `403`  | `{"error": "Forbidden", "message": "API key does not have the required scope (requires: leads:view)."}`          | Key is missing the required permission    |
| `403`  | `{"error": "Forbidden", "message": "You do not have permission to perform this action (requires: leads:view)."}` | Your role lacks the required permission   |