Copy page

Guides

Using API Keys

API keys authenticate your requests to the Neuratel API. Each key can be scoped to specific permissions, making it safe to create per-service keys with only the access needed.

Key Format

All Neuratel API keys start with nk_live_.

Creating an API Key

1. Go to Settings → API Keys
2. Click Create API Key
3. Enter a descriptive name (e.g., "Backend Service", "Campaign Manager")
4. Select the scopes you need
5. Click Create
6. Copy the key immediately — it is only shown once

Store it in a secrets manager or environment variable immediately. If lost, you'll need to create a new key.

Using an API Key

Include the key in the Authorization header with every request:

Code
curl https://api.neuratel.ai/v1/agents \
  -H "Authorization: Bearer nk_live_abc123xyz789"

Code
import httpx

client = httpx.Client(
    base_url="https://api.neuratel.ai",
    headers={"Authorization": "Bearer nk_live_abc123xyz789"},
)
agents = client.get("/v1/agents").json()

Code
const response = await fetch("https://api.neuratel.ai/v1/agents", {
  headers: { Authorization: "Bearer nk_live_abc123xyz789" },
});
const agents = await response.json();

If the key lacks a required scope, the API returns:

Code
{
  "error": {
    "type": "authentication_error",
    "code": "AUTH_1003",
    "message": "Insufficient permissions. Required scope: agents:edit",
    "request_id": "req_xyz789"
  }
}

Available Scopes

Select only the scopes each key actually needs:

Scope	Description
agents:view	Read agent configurations
agents:create	Create new agents
agents:edit	Update agent settings
agents:delete	Delete agents
agents:call	Initiate outbound calls
calls:view	View call logs, transcripts, recordings
campaigns:view	View campaign details and stats
campaigns:create	Create campaigns
campaigns:start	Start/pause/stop campaigns
numbers:view	View phone numbers
numbers:edit	Assign and update numbers
webhooks:view	View webhook configurations
integrations:create	Create and manage integrations
analytics:view	Access analytics dashboards and reports
billing:view	View balance and invoices
knowledge:view	View knowledge base content
knowledge:create	Upload and manage KB documents
team:view	View team members
team:invite	Invite team members

Managing Keys

All key management — listing, renaming, rotating, and revoking — is done from Settings → API Keys in the dashboard.

Rotation: Click the ⟳ Rotate button next to a key. The old key continues working for a configurable grace period while you deploy the new one. This allows zero-downtime rotation.

Revocation: Click Revoke to immediately invalidate a key. Any requests using it will receive AUTH_1001.

Best Practices

• One key per service — create separate keys for your backend, campaign runner, analytics pipeline, etc.
• Minimum required scopes — grant only the permissions each service actually needs
• Never hardcode keys — use environment variables or a secrets manager
• Rotate regularly — rotate quarterly or when team members with key access leave
• Monitor usage — identify and revoke unused keys from the dashboard

Next Steps

• Security — webhook verification and data encryption
• Production Checklist — verify API keys are production-ready
• Managing Your Team — role-based access for team members