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

# API Keys

> Generate and manage secure API keys for programmatic access to botBrains

<Tip>
  API keys are in private beta. If you would like access, please contact [support@botbrains.io](mailto:support@botbrains.io).
</Tip>

API keys enable programmatic access to your botBrains projects. You can build custom integrations, automate workflows, and scope each key with specific permissions for secure, controlled access.

## Authentication

API keys authenticate requests using a bearer token scheme:

```bash Example API Request theme={null}
curl https://api.botbrains.io/v1/projects/123/conversations \
  -H "Authorization: Bearer sk_live_abc123def456..." \
  -H "Content-Type: application/json"
```

Each key consists of a **prefix** (`sk_live_` or `sk_test_`), a cryptographically secure **secret** (43 characters), and a set of **permissions** that control which operations the key can perform.

<Warning>
  Treat API keys like passwords. Never commit them to version control, share them in public channels, or expose them in client-side code.
</Warning>

## Key Concepts

* **Project-scoped**: Each key belongs to one project and cannot access resources from other projects.
* **Permission-based**: Keys use granular `resource:action` permissions (for example `conversation:read`, `knowledge:write`). Grant only the minimum permissions required.
* **Revocable**: You can delete or modify key permissions at any time - changes take effect immediately.

## Creating a Key

<Steps>
  <Step title="Open API Keys">
    Open [Settings → API Keys](https://platform.botbrains.io/~/settings/apikeys) in your project
  </Step>

  <Step title="Create and configure">
    Click **Create API Key**, enter a descriptive name (for example "CRM Sync", "CI Pipeline"), and select the permissions the key needs
  </Step>

  <Step title="Copy the secret">
    Copy the secret immediately - you won't see it again after closing the dialog
  </Step>
</Steps>

Store the secret in environment variables or a secrets manager, never in source code:

```bash .env theme={null}
BOTBRAINS_API_KEY=sk_live_Np8JQxH7mF3vKL9wRt2YzBnX4cDq6sA1pWe5iUoGhMj
BOTBRAINS_PROJECT_ID=123
```

<img src="https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/api-keys/create-api-key-dialog.png?fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=c8de305cb4ab505f9324db54c476d860" alt="Create API Key dialog showing name field and permission selection" data-generation-prompt="Navigate to Settings > API Keys on platform.botbrains.io. Click the 'Create API Key' button to open the creation dialog. Show the dialog with a sample name like 'CRM Sync' entered and several permissions selected (e.g. conversation:read, knowledge:write). Capture the full dialog with the secret revealed or ready to copy." data-og-width="1920" width="1920" data-og-height="1080" height="1080" data-path="images/api-keys/create-api-key-dialog.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/api-keys/create-api-key-dialog.png?w=280&fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=442399747dc4d978cbd342a8bf7a38fe 280w, https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/api-keys/create-api-key-dialog.png?w=560&fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=885c63e262a25df4b2d16acf689ccfe7 560w, https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/api-keys/create-api-key-dialog.png?w=840&fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=158b7a5b0d8b1a4b38fded781f7ccf06 840w, https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/api-keys/create-api-key-dialog.png?w=1100&fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=8c80375146def3977da1f0fb0e1a7651 1100w, https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/api-keys/create-api-key-dialog.png?w=1650&fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=83cc0922f1e894aac762eae07acea5ab 1650w, https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/api-keys/create-api-key-dialog.png?w=2500&fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=f0da494624146abd738c7558939d6997 2500w" />

## Managing Keys

The API Keys table shows each key's name, masked secret, and permissions. From there you can:

* **Reveal or copy** the secret using the eye / copy icons
* **Edit permissions** without regenerating the secret (click the pencil icon)
* **Delete a key** permanently (all requests using it will fail immediately)

<img src="https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/api-keys/api-keys-table.png?fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=f7390a3b99ddbc8419ede218af6013db" alt="API Keys table showing multiple keys with masked secrets and action icons" data-generation-prompt="Navigate to Settings > API Keys on platform.botbrains.io. Display the API Keys management table with at least 2-3 sample API keys listed (e.g. 'CRM Sync', 'CI Pipeline', 'Analytics Reader'). Show the masked secret column (ending in visible characters), the permissions column, and the action icons (eye, copy, pencil, delete) on the right side of each row. Use realistic data, not empty states." data-og-width="1280" width="1280" data-og-height="720" height="720" data-path="images/api-keys/api-keys-table.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/api-keys/api-keys-table.png?w=280&fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=32786987e6a0be506f9955da6e642320 280w, https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/api-keys/api-keys-table.png?w=560&fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=0e352d83a76a9432c03664580c000f6a 560w, https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/api-keys/api-keys-table.png?w=840&fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=19909c63ef73eb4b6a2119ee69dab224 840w, https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/api-keys/api-keys-table.png?w=1100&fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=f292e08392772827dae266b435de2e05 1100w, https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/api-keys/api-keys-table.png?w=1650&fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=31bfbe9708e21ab02c01cdb101dc9923 1650w, https://mintcdn.com/botbrains/mrGgmLFCJjw3qsuy/images/api-keys/api-keys-table.png?w=2500&fit=max&auto=format&n=mrGgmLFCJjw3qsuy&q=85&s=2ef0ee77329e669ee09f5106f23cbfd9 2500w" />

## Permissions

Permissions follow a `resource:action` pattern and map directly to the [Roles and Permissions](/concepts/roles-permissions) system. Write permissions automatically include the corresponding read permission.

Common patterns:

| Use case            | Permissions                                                                         |
| ------------------- | ----------------------------------------------------------------------------------- |
| Read-only analytics | `project:read`, `conversation:read`, `metric:read`, `topic:read`                    |
| Knowledge sync      | `knowledge:read`, `knowledge:write`, `table:read`, `table:write`                    |
| Conversation access | `conversation:read`, `conversation:write`, `conversation:generate`, `userpool:read` |

<Note>
  API keys only support project-level permissions. Organization-level operations (billing, team management) require authenticated user sessions.
</Note>

## Next Steps

* [Roles and Permissions](/concepts/roles-permissions) - Understand the full permission model
* [Triggers](/concepts/triggers) - Automate actions with event-based webhooks
* [Data Export](/concepts/data-export) - Export conversation data programmatically