> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botcadence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> Authenticate Campaign API requests with a project API key

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

```bash theme={null}
X-API-Key: bot_live_YOUR_KEY
```

Do **not** use `Authorization: Bearer` for these endpoints.

## Create a key

<Steps>
  <Step title="Open project settings">
    In the [dashboard](https://app.botcadence.com), open your project → **Project Settings → API Keys**.
  </Step>

  <Step title="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`).
  </Step>

  <Step title="Copy the secret">
    Copy the plain key immediately. Botcadence stores only a hash and will not show the full value again.
  </Step>
</Steps>

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

## Key format

```
bot_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```

## Header

Send the key on every request:

```bash theme={null}
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

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://backend.botcadence.com/organizations/ORG_ID/projects/PROJECT_ID/campaigns" \
    -H "X-API-Key: bot_live_YOUR_KEY"
  ```

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

  ```python Python theme={null}
  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"]},
  )
  ```
</CodeGroup>

## 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.