Authentication

API keys

Keys are created per workspace and can be limited to the exact resources an integration needs: agents, channels, contacts, contact lists, calls, conversations, campaigns, conversions, goals, competencies, webhooks, clinic setup, business scheduling, the agenda, automated testing and knowledge. The same key works with the REST API and the MCP server. You can create several keys for different applications or environments.

Key format

sk_…

A workspace key: sk_<8-hex-prefix>_<48-hex-secret>, such as sk_51e4f2a9_…. The dashboard shows the 8-character prefix, so you can tell your keys apart.

rk_…

A reseller key: it reaches a reseller's client workspaces, one client per request. See Reseller API and MCP.

Create a key

1. 1

   Open Settings → API keys

   In the dashboard, open Settings in the sidebar and choose the API Keys tab.

2. 2

   Name it

   Click Create key and name it after the app or assistant that will use it, for example “Production app” or “Development”.

3. 3

   Choose what it can reach

   Set each resource to None, Read or Write (write includes read), and give only what the integration needs. You can change it later with Edit access.

4. 4

   Review its safety settings

   Deletes and changes wait for approval unless an owner or admin turns that off. You can also let AI assistants make changes over MCP, set an expiry date and limit the IP addresses it works from.

5. 5

   Copy the key

   NuTalk shows it once: store it somewhere safe. If you lose it, roll the key to get a new one.

Send the key

Send the key in the Authorization header as a Bearer token: Authorization: Bearer sk_….

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

Who can manage keys

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.

A key made with an earlier version of Settings can also hold clinic:write: it only changes an appointment's doctor, and Settings no longer offers it.

Some requests need more than their own scope:

• contacts:write also defines custom fields and adds numbers to the exclusion list.
• A contact import needs contacts:write and the write scope of where it lands: campaigns:write into a campaign; contact_lists:write into a list, plus campaigns:write when that list feeds an outbound campaign.
• Adding or removing the members of a list that feeds a campaign also needs campaigns:write: it enrolls or removes people. So does deleting a list linked to a campaign.
• Conversation events on a webhook need conversations:read as well as webhooks:write: to register an endpoint for them, to add them to one, and to change the URL of, or switch back on, an endpoint that receives them.
• Call events on a webhook, and * which includes them, need calls:read as well: they carry each call's numbers and outcome. So does changing the campaigns of an endpoint that receives them, since those decide whose calls it gets.
• calls:write places calls, which spend credits, and ends calls in progress. campaigns:write starts campaigns, which call every enrolled contact.
• Trying a held WhatsApp account's templates again needs campaigns:write as well as channels:write: it starts again the campaigns the hold paused, which send to customers.
• agents:write also archives an agent, which takes it off its channels.
• Clinic setup, business scheduling, the agenda, automated testing, knowledge and channel setup act as the workspace member who created the key, with at most an admin's role: a key never does more there than that person can. If that person changes role or leaves the workspace, the key stops working and answers 401; create a new key.

Expiry dates and allowed addresses

In Settings → API keys you can give a key an expiry date and a list of the IP addresses it may be used from (single IPv4 or IPv6 addresses, or CIDR ranges such as 198.51.100.0/24). Both apply to the REST API and to MCP.

• After its expiry date a key answers 401 with api_key_expired.
• From an address that is not on its list, a key answers 403 with ip_not_allowed, and the attempt is recorded in the workspace's audit log.

Approvals

A key's deletes and changes can wait for an owner's or admin's approval: Deletes wait for approval and Changes wait for approval are on for every new key, and only owners and admins can turn them off. Such a call answers 202 with a change request instead of running, and runs once approved in Settings → API keys. Reading, creating and stopping something never wait. See Approvals.

Keep keys safe

Store keys in environment variables, never in code:

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

• Use a separate key for each environment (development, staging and production) and each integration, so a leaked key reaches less and revoking one breaks nothing else.
• Change secrets from time to time: Roll key… gives a key a new secret, and the old one keeps working until the time you choose. An expiry date limits how long a key works at all.
• Call the API from your server only. Never use a key in client-side JavaScript.

Revoke a key

If a key may have leaked, or you no longer need it, revoke it:

1. 1

   Open Settings → API keys

2. 2

   Choose Revoke… in the key's menu

   Or Revoke key… in its details.

3. 3

   Confirm with Revoke

A key also stops working for good when the person who created it changes role (a promotion included) or leaves the workspace. The workspace's owners and admins are told which keys stopped; create a new key for each integration that used one.

Authentication errors

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

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