Copy page

Core Concepts

API Keys

API keys authenticate programmatic requests to the Neuratel API. Every request must include a valid key in the Authorization header.

Key Format

All Neuratel API keys start with nk_live_. Keys are scoped to a single organization. A key created in one organization cannot access resources in another.

Authentication

Include your API key as a Bearer token in every request:

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

Code
import os, httpx

response = httpx.get(
    "https://api.neuratel.ai/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['NEURATEL_API_KEY']}"},
)

Code
const response = await fetch("https://api.neuratel.ai/v1/agents", {
  headers: { Authorization: `Bearer ${process.env.NEURATEL_API_KEY}` },
});

---

Creating an API Key

API keys are managed from Settings → API Keys in the dashboard.

1. Click Create API Key
2. Enter a descriptive name (e.g., "Production Backend")
3. Select the scopes this key needs
4. Click Create

The full key value is shown exactly once. Copy it and store it securely — you cannot retrieve it again.

---

Scopes

Each key is restricted to the scopes you select at creation. A key without a required scope receives 403 Forbidden.

Scope	Description
agents:view	Read agent configurations
agents:create	Create new agents
agents:edit	Modify existing agents
agents:delete	Delete agents
agents:call	Initiate outbound calls and web calls
analytics:view	View call logs, transcripts, recordings, and analytics
campaigns:view	Read campaign data
campaigns:create	Create campaigns
campaigns:start	Start, pause, and stop campaigns
numbers:view	List phone numbers
numbers:edit	Assign and update numbers
knowledge:view	View knowledge base content
knowledge:create	Upload and manage KB documents
webhooks:view	View webhook configurations
integrations:view	View MCP integrations
integrations:create	Create and manage integrations
billing:view	View balance and invoices
team:view	View team members
team:invite	Invite team members

---

Managing Keys

All key management is done from Settings → API Keys:

• List — all active and revoked keys are visible
• Rotate — generates a replacement key with the same permissions; the old key stays valid for a configurable grace period to enable zero-downtime transitions
• Revoke — immediately invalidates the key; irreversible

---

Security Best Practices

• Store keys in environment variables — never hardcode keys in source code
• Never commit keys to version control — add .env to .gitignore
• Minimum required scopes — give each key only the permissions it needs
• Separate keys per environment — distinct keys for development, staging, and production
• Separate keys per service — different keys for your backend, campaign runner, analytics pipeline
• Rotate regularly — use the Rotate button with a grace period for zero-downtime transitions

---

Common Errors

Error	Cause	Fix
AUTH_1001	Key is invalid or revoked	Verify the key and check its status in the dashboard
AUTH_1002	Key has expired	Rotate the key from the dashboard
AUTH_1003	Key lacks required scope	Create a new key with the correct scopes

---

Next Steps

• Using API Keys — detailed guide on creating, rotating, and managing keys
• Agents — use your API key to create and manage agents
• Authentication — full authentication reference