Authentication
All API requests must be authenticated using an API key. API keys provide stateless, scoped authentication for programmatic access.
| Environment | Prefix | Example |
|---|
| Production | nl_live_ | nl_live_a1b2c3d4e5f6... (64 hex chars) |
| Test | nl_test_ | nl_test_a1b2c3d4e5f6... (64 hex chars) |
Passing your API key
You can authenticate using either method:
Option 1: X-API-Key header (recommended)
curl -H "X-API-Key: nl_live_YOUR_API_KEY" \
https://api.naturalead.ai/api/leads
curl -H "Authorization: Bearer nl_live_YOUR_API_KEY" \
https://api.naturalead.ai/api/leads
When both X-API-Key and Authorization: Bearer nl_* are present, the X-API-Key header takes precedence.
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:
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 |
When creating an API key, you can only grant scopes that your own role has permission for. This prevents privilege escalation.
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 |
