Authentication
All /v1 endpoints require an API key. Keys are scoped — you only grant the permissions your integration needs.
API key format
All NextNeural API keys start with nn_k_:
nn_k_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Pass it as a Bearer token in every request:
Authorization: Bearer nn_k_your_key_here
Creating an API key
- Go to Settings → API Keys in the dashboard
- Click New API Key and give it a name
- Select the scopes you need (see table below)
- Copy the key — it is shown only once
Scopes
| Scope | What it allows |
|---|---|
voice:calls:read | List calls, get transcripts, call stats |
voice:calls:write | Trigger calls, end calls, write call metadata |
voice:campaigns:read | List campaigns and their metrics |
voice:campaigns:write | Launch, stop, and manage campaigns |
voice:contacts:read | List and search contacts |
voice:contacts:write | Create, update, delete, and bulk-import contacts |
voice:webhooks:read | List webhooks and delivery logs |
voice:webhooks:write | Register and delete webhooks |
Assign only the scopes your application requires. A key missing a required scope receives 403 Forbidden.
Error responses
| Status | Meaning |
|---|---|
401 Unauthorized | Key is missing, malformed, or revoked |
403 Forbidden | Key is valid but lacks the required scope |
{ "detail": "Invalid or expired token" }
{ "detail": "Insufficient permissions. Required scopes: voice:calls:write" }
WebSocket authentication
WebSocket endpoints accept the token as a query parameter:
wss://api.nextneural.ai/ws/live/{call_uuid}?token=nn_k_your_key_here