API Keys

API keys authenticate your requests to the Callers API. Use them to create agents, upload contacts, start calls, and read results from your own systems. Each key belongs to your organization, not to the person who created it, so it keeps working if that person leaves the team.

Before you start

You need the Admin role.
Your Manage API keys access must be on. See Team and permissions.
In a subaccount, the parent account must allow API Keys for that subaccount.

If you don’t see API Keys in Settings, one of these conditions isn’t met.

Create an API key

Open API Keys

Click your name in the sidebar, choose Settings, and open API Keys.

Start a new key

Click Create at the top of the section. If you have no keys yet, click Add API key.

Name the key

In Create new API key, enter an API Key name that says where the key is used, for example crm-sync-production. Click Create.

The new key appears in the table with its Name, API key, and Created on date.

Settings window with API Keys selected in the left navigation, a Create button, and a table with Name, API key, and Created on columns where the key value is hidden behind a Show link — Settings → API Keys, with the Create button and the Show link for each key.

Copy a key

In the API key column, click Show to display the key, then click the copy icon next to it. Store the key in your secrets manager or environment variables right away.

Delete (revoke) a key

Hover over the key’s row and click the delete icon. Confirm with Yes, revoke. Requests that use the key are rejected from then on, so update your integrations first. Keys don’t expire. Delete keys you no longer use.

Use your API key

Send the key as the raw value of the Authorization header. Don’t add a Bearer prefix.

curl https://api.callers.ai/organization \
  -H "Authorization: $CALLERS_API_KEY"

const res = await fetch("https://api.callers.ai/organization", {
  headers: { Authorization: process.env.CALLERS_API_KEY },
});
const body = await res.json();
console.log(body);

import os
import requests

res = requests.get(
    "https://api.callers.ai/organization",
    headers={"Authorization": os.environ["CALLERS_API_KEY"]},
)
print(res.json())

Act on behalf of a subaccount

A key created in a main (parent) account can also act on any of its subaccounts. Add the x-sub-organization-id header with the subaccount’s ID. Without the header, requests act on the account that owns the key.

curl https://api.callers.ai/agents \
  -H "Authorization: $CALLERS_API_KEY" \
  -H "x-sub-organization-id: 64f1c2e9a1b2c3d4e5f60789"

const res = await fetch("https://api.callers.ai/agents", {
  headers: {
    Authorization: process.env.CALLERS_API_KEY,
    "x-sub-organization-id": "64f1c2e9a1b2c3d4e5f60789",
  },
});

res = requests.get(
    "https://api.callers.ai/agents",
    headers={
        "Authorization": os.environ["CALLERS_API_KEY"],
        "x-sub-organization-id": "64f1c2e9a1b2c3d4e5f60789",
    },
)

The subaccount must belong to the account that owns the key. Otherwise the request is rejected. See Managing subaccounts.

If you use a custom domain, you can also call the API at https://<your-domain>/api.

Security best practices

Keep keys server-side. Never put an API key in browser code, mobile apps, or public repositories. To add a voice agent to a website, use the web widget instead.
Use one key per integration. Separate keys let you revoke one integration without breaking the others, and the key name shows where each one is used.
Store keys in a secrets manager or environment variables, not in source code or spreadsheets.
Rotate keys. Create a new key, deploy it, then revoke the old one. Do this right away if a key may have leaked.
Limit who can see keys. Turn off Manage API keys for Admins who don’t need it.
Verify traffic in the other direction too. API keys authenticate your requests to Callers. To confirm that webhooks and HTTP actions really come from Callers, check their signatures. See Validating webhook signatures.

Troubleshooting

My requests are rejected as unauthorized

Check that the Authorization header contains only the key, with no Bearer prefix or extra spaces, and that the key hasn’t been revoked. If you send x-sub-organization-id, make sure the subaccount belongs to the account that owns the key.

I don't see the API Keys section

Only Admins with Manage API keys access see it. In a subaccount, the parent account must also allow API keys. Ask an Admin, or email .

The API returns data from the wrong account

Each key acts on the account where it was created. Create the key in the right account, or use a parent account key with x-sub-organization-id.

API introduction

Base URL, response format, errors, and pagination.

Managing subaccounts

Create and manage client accounts.

Team and permissions

Control who can manage API keys.

Validating webhook signatures

Verify requests that Callers sends to you.

Get started

Build your agent

Test and deploy

Voice

Channels

Contacts and outreach

Results and analytics

Human operators

Best practices

Account and administration

Enterprise

Resources

Before you start

Create an API key

Copy a key

Delete (revoke) a key

Use your API key

Act on behalf of a subaccount

Security best practices

Troubleshooting

API introduction

Managing subaccounts

Team and permissions

Validating webhook signatures

​Before you start

​Create an API key

​Copy a key

​Delete (revoke) a key

​Use your API key

​Act on behalf of a subaccount

​Security best practices

​Troubleshooting

​Related

API introduction

Managing subaccounts

Team and permissions

Validating webhook signatures

Before you start

Create an API key

Copy a key

Delete (revoke) a key

Use your API key

Act on behalf of a subaccount

Security best practices

Troubleshooting

Related