Copy page

Getting Started

Authentication

Neuratel Studio has two authentication methods:

Method	How It Works	When to Use
API Keys	Authorization: Bearer nk_live_... header	Server-to-server calls, integrations, automation
Session	Browser session (handled automatically)	Dashboard access at app.neuratel.ai

API Keys

Key Format

All Neuratel API keys start with nk_live_. Create a separate key per service or integration — this lets you revoke a key without affecting others.

Creating a Key

1. Go to Organization → API Keys in the dashboard
2. Click Create Key
3. Set a name (e.g., prod-backend, ci-pipeline)
4. Optionally set an expiration date
5. Click Create and copy the key immediately — it will not be shown again

Using a Key in Requests

Pass the key in the Authorization header on every request:

Code
# cURL
curl -X GET "https://api.neuratel.ai/v1/agents" \
  -H "Authorization: Bearer nk_live_your_api_key" \
  -H "Content-Type: application/json"

Code
# Python (requests)
import os
import httpx

headers = {
    "Authorization": f"Bearer {os.environ['NEURATEL_API_KEY']}",
    "Content-Type": "application/json",
}

response = httpx.get("https://api.neuratel.ai/v1/agents", headers=headers)
agents = response.json()

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

const agents = await response.json();

Key Scopes

API keys carry a set of scopes that restrict what they can do. When creating a key you can select a preset or choose individual scopes.

Presets:

Preset	Description
full_access	All permissions (default)
standard	Create/edit agents, run campaigns, view analytics — no admin actions
read_only	View-only access to agents, analytics, numbers, campaigns

Individual scope examples:

Scope	What It Allows
agents:view	List and fetch agents
agents:create	Create new agents
agents:edit	Update agent config
agents:delete	Delete agents
agents:call	Trigger outbound calls via an agent
analytics:view	View call summaries and metrics
analytics:hangup	Hang up calls and barge into live calls
campaigns:view	List campaigns
campaigns:create	Create and configure campaigns
campaigns:start	Start a campaign
numbers:view	List phone numbers
knowledge:view	Read knowledge base entries

If a request is made with a key that lacks the required scope, the API returns 403 Forbidden.

Key Rotation

Rotate a key from Settings → API Keys using the Rotate button. The old key stays valid for a configurable grace period while you deploy the new one, then expires automatically — zero downtime.

Error Responses

All authentication errors use the standard error envelope:

Code
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid or has been revoked.",
    "request_id": "req_01JRK8Z2QA4BN7P3F6KXMYD9"
  }
}

HTTP Status	When
401 Unauthorized	Missing header, invalid key, expired key, revoked key
403 Forbidden	Valid key but missing required scope
429 Too Many Requests	Repeated failed authentication attempts (brute-force protection)

For security, 401 is returned for all key failures — the response does not distinguish between a key that doesn't exist vs. one that has been revoked.

Session Authentication

Dashboard access at app.neuratel.ai uses session-based authentication. Sessions are established on login and managed automatically by the browser. No manual configuration is needed.

Sessions expire after a period of inactivity. If you're redirected to the login page, your session has expired — sign in again.

Security Best Practices

1. Never commit keys to source control — use environment variables or a secrets manager
2. One key per service — create a dedicated key for each application that calls the API
3. Minimal scope — use read_only or standard presets unless your integration specifically needs full_access
4. Set expiration dates — time-limited keys reduce exposure if a key is leaked
5. Rotate after team changes — rotate or revoke keys when a team member with API access leaves
6. Monitor last-used timestamps — unexpected recent activity on a key you haven't used is a signal to rotate it

Environment Variable Pattern

Code
# .env (never commit this file)
NEURATEL_API_KEY=nk_live_your_api_key_here

Code
# Load in Python
import os
api_key = os.environ["NEURATEL_API_KEY"]

Code
// Load in Node.js
const apiKey = process.env.NEURATEL_API_KEY;

What's Next

• Quickstart — use your API key to create your first agent
• API Reference — complete endpoint documentation
• Platform Overview — understand how agents, calls, and webhooks fit together