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)

curl -H "X-API-Key: nl_live_YOUR_API_KEY" \
  https://api.naturalead.ai/api/leads

Option 2: Bearer token

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

Getting Started

Reference

Authentication

Authentication

Key format

Passing your API key

Key security

Creating API keys

Key lifecycle

Scopes and Permissions

Available scopes

Error responses

​Authentication

​Key format

​Passing your API key

​Key security

​Creating API keys

​Key lifecycle

​Scopes and Permissions

​Available scopes

​Error responses

Authentication

Key format

Passing your API key

Key security

Creating API keys

Key lifecycle

Scopes and Permissions

Available scopes

Error responses