Authentication

All Campaign API requests are authenticated with a project API key.

X-API-Key: bot_live_YOUR_KEY

Do not use Authorization: Bearer for these endpoints.

Create a key

Open project settings

In the dashboard, open your project → Project Settings → API Keys.

Create the key

Click Create API key, give it a name, and select the scopes your integration needs (for outbound calls, select Outbound calls / calls:create).

Copy the secret

Copy the plain key immediately. Botcadence stores only a hash and will not show the full value again.

Never commit API keys to source control or expose them in client-side code. Call the API from your server only.

Key format

bot_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Send the key on every request:

X-API-Key: bot_live_YOUR_KEY

The key must belong to the same organization and project as the IDs in the URL path.

Scopes

Scope	Description
`calls:create`	Trigger outbound campaign calls (`trigger-call`)

Create keys with the scopes required for the endpoints you call.

Example

curl -X GET "https://backend.botcadence.com/organizations/ORG_ID/projects/PROJECT_ID/campaigns" \
  -H "X-API-Key: bot_live_YOUR_KEY"

const response = await fetch(
  `https://backend.botcadence.com/organizations/${organizationId}/projects/${projectId}/campaigns`,
  {
    headers: {
      "X-API-Key": process.env.BOTCADENCE_API_KEY,
    },
  }
);

import os
import requests

response = requests.get(
    f"https://backend.botcadence.com/organizations/{organization_id}/projects/{project_id}/campaigns",
    headers={"X-API-Key": os.environ["BOTCADENCE_API_KEY"]},
)

Common auth errors

Situation	Typical result
Missing `X-API-Key`	`401` Unauthorized
Invalid or revoked key	`401` Unauthorized
Key for a different org or project	`403` Forbidden
Key missing a required scope	`403` Forbidden

Revoke a key

From Project Settings → API Keys, revoke any key that is compromised or no longer needed. Revoked keys stop working immediately.

Getting Started

Organization

Projects

Chat Agent

Voice Agent

API Reference

Create a key

Key format

Header

Scopes

Example

Common auth errors

Revoke a key

​Create a key

​Key format

​Header

​Scopes

​Example

​Common auth errors

​Revoke a key

Create a key

Key format

Header

Scopes

Example

Common auth errors

Revoke a key