Authentication

API requests are authenticated with a project API key. An API key is a private access code for a program, similar to a password. It tells Botcadence which project is making the request. You only need this page when another program will connect to Botcadence; dashboard users sign in normally.

Authorization: Bearer bot_live_YOUR_KEY

Send the key in the Authorization: Bearer header on every request.

Create a key

Open project settings

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

Create the key

Click Create API key, give it a name, and select the scopes your integration needs. Scopes use the resource:action form.

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:

Authorization: Bearer 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`	Create outbound campaign calls (`POST .../campaigns/{id}/calls`)
`automations:create`	Send a custom event to project automation rules
`whatsapp:create`	Send the approved template attached to a broadcast

Create keys with the scopes required for the endpoints you call. Read, update, and delete scopes will be available for resources when those API actions are supported. Existing API keys that used automations:trigger or whatsapp:send are migrated to automations:create and whatsapp:create before this scope contract is deployed. Create new keys with the resource-action scopes listed above.

Example

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

const response = await fetch(
  `https://backend.botcadence.com/organizations/${organizationId}/projects/${projectId}/campaigns`,
  {
    headers: {
      "Authorization": `Bearer ${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={"Authorization": f"Bearer {os.environ['BOTCADENCE_API_KEY']}"},
)

Common auth errors

Situation	Typical result
Missing `Authorization: Bearer`	`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 Admin → Settings → API Keys, revoke any key that is compromised or no longer needed. Revoked keys stop working immediately.

Getting Started

Organization

Projects

Operate

Insights

Outreach

Build

Deploy

Admin

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