API Reference

Authentication

Secure your API requests using Bearer token authentication with API keys.

Overview

The Nutalk API uses API keys to authenticate requests. API keys are scoped to your workspace and can be limited to the exact resources an integration needs: agents, channels, contacts, contact lists, calls, campaigns, goals, and competencies. You can create multiple API keys for different applications or environments.

Key Format

API keys follow the format: sk_<8-hex-prefix>_<48-hex-secret>

sk_51e4f2a9_... — Workspace API keys
The 8-character prefix is shown in the dashboard so you can identify and rotate keys.

Using API Keys

Include your API key in the Authorization header as a Bearer token:

curl

curl -X GET "https://www.nutalk.ai/v1/agents" \
  -H "Authorization: Bearer YOUR_NUTALK_API_KEY"

Verify a Key

Use the verification endpoint before deploying a new integration.

bash

curl "https://www.nutalk.ai/v1/auth/verify" \
  -H "Authorization: Bearer $NUTALK_API_KEY"

json

{
  "success": true,
  "data": {
    "authenticated": true,
    "api_key": {
      "id": "7b7a0ce4-5b7d-4a0f-aad3-f3c0a1a84b54",
      "name": "Production backend",
      "prefix": "51e4f2a9",
      "scopes": ["agents:read", "calls:read", "calls:write"]
    },
    "workspace": {
      "id": "d3b85d84-ef8f-4c4a-8d18-3fa23e7fd48a",
      "name": "Acme",
      "slug": "acme",
      "status": "active"
    },
    "verified_at": "2026-05-08T18:45:00.000Z"
  }
}

Creating API Keys

Generate keys from your workspace settings.

1
Navigate to Settings
From your dashboard, click Settings in the sidebar.
2
Open API Keys
Select the API Keys tab.
3
Create Key
Click Create Key and enter a descriptive name (e.g., “Production App” or “Development”).
4
Choose Permissions
Select only the read and write scopes the integration needs. You can edit these permissions later from the same API Keys tab.
5
Copy Your Key
Copy the key immediately—it won't be displayed again after you leave the page.

Keep your API key secret

Your API key can access public API resources in your workspace. Never commit keys to version control, share them in client-side code, or expose them publicly.

API Key Scopes

Every endpoint checks a resource scope before it runs. Use read scopes for list and get requests, and write scopes for create, update, delete, or action requests.

Resource	Read Scope	Write Scope
Agents	agents:read	agents:write
Channels	channels:read	N/A
Contacts	contacts:read	contacts:write
Contact Lists	contact_lists:read	contact_lists:write
Calls	calls:read	calls:write
Campaigns	campaigns:read	campaigns:write
Goals	goals:read	goals:write
Competencies	competencies:read	competencies:write

Verify is always available

A valid key can always call /v1/auth/verify. The verify response includes the key's granted scopes so your integration can confirm permissions before running.

Security Best Practices

Protect your API keys and your users' data.

Use Environment Variables

Store API keys in environment variables, never in code:

.env

# .env file (never commit this!)
NUTALK_API_KEY=YOUR_NUTALK_API_KEY

Use Separate Keys for Environments

Create different API keys for development, staging, and production. This limits blast radius if a key is compromised.

Rotate Keys Periodically

Generate new keys periodically and revoke old ones. This ensures any leaked keys have limited lifetime.

Server-Side Only

Never use API keys in client-side JavaScript. Always make API calls from your backend server.

Revoking API Keys

Immediately disable compromised or unused keys.

If you believe an API key has been compromised, or if it's no longer needed, revoke it immediately:

Go to Settings → API Keys
Find the key you want to revoke
Click the Revoke button
Confirm the revocation

Revocation is immediate

Revoked keys will stop working instantly. All API requests using the revoked key will return 401 Unauthorized.

Authentication Errors

When authentication fails, the API returns one of these errors:

Status	Error Code	Description
401	unauthorized	Missing or invalid Authorization header
401	invalid_api_key	The API key is invalid or has been revoked
403	forbidden	The API key is missing the required resource scope
429	rate_limited	Too many requests—slow down

Example Error Response

json

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header. Expected: Bearer sk_xxxxxxxx_xxx"
  }
}

Rate Limits

API requests are subject to rate limits. See Rate Limits for details on limits and best practices.

AnteriorAPI Reference SiguienteAgents API

Overview

Key Format

API keys follow the format: sk_<8-hex-prefix>_<48-hex-secret>

sk_51e4f2a9_... — Workspace API keys
The 8-character prefix is shown in the dashboard so you can identify and rotate keys.

{ "success": true, "data": { "authenticated": true, "api_key": { "id": "7b7a0ce4-5b7d-4a0f-aad3-f3c0a1a84b54", "name": "Production backend", "prefix": "51e4f2a9", "scopes": ["agents:read", "calls:read", "calls:write"] }, "workspace": { "id": "d3b85d84-ef8f-4c4a-8d18-3fa23e7fd48a", "name": "Acme", "slug": "acme", "status": "active" }, "verified_at": "2026-05-08T18:45:00.000Z" } }

API Key Scopes

Every endpoint checks a resource scope before it runs. Use read scopes for list and get requests, and write scopes for create, update, delete, or action requests.

Resource	Read Scope	Write Scope
Agents	agents:read	agents:write
Channels	channels:read	N/A
Contacts	contacts:read	contacts:write
Contact Lists	contact_lists:read	contact_lists:write
Calls	calls:read	calls:write
Campaigns	campaigns:read	campaigns:write
Goals	goals:read	goals:write
Competencies	competencies:read	competencies:write

Verify is always available

A valid key can always call /v1/auth/verify. The verify response includes the key's granted scopes so your integration can confirm permissions before running.

Authentication Errors

When authentication fails, the API returns one of these errors:

Status	Error Code	Description
401	unauthorized	Missing or invalid Authorization header
401	invalid_api_key	The API key is invalid or has been revoked
403	forbidden	The API key is missing the required resource scope
429	rate_limited	Too many requests—slow down

Example Error Response

json

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header. Expected: Bearer sk_xxxxxxxx_xxx"
  }
}