API Keys

API keys are in private beta. If you would like access, please contact support@botbrains.io.

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:

Example API Request

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.

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

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

Open API Keys

Open Settings → API Keys in your project

Create and configure

Click Create API Key, enter a descriptive name (for example “CRM Sync”, “CI Pipeline”), and select the permissions the key needs

Copy the secret

Copy the secret immediately - you won’t see it again after closing the dialog

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

.env

BOTBRAINS_API_KEY=sk_live_Np8JQxH7mF3vKL9wRt2YzBnX4cDq6sA1pWe5iUoGhMj
BOTBRAINS_PROJECT_ID=123

Create API Key dialog showing name field and permission selection

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)

API Keys table showing multiple keys with masked secrets and action icons

Permissions

Permissions follow a resource:action pattern and map directly to the Roles and 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`

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

Next Steps

Roles and Permissions - Understand the full permission model
Triggers - Automate actions with event-based webhooks
Data Export - Export conversation data programmatically

Security Settings

Settings

Legal

Authentication

Key Concepts

Creating a Key

Managing Keys

Permissions

Next Steps

​Authentication

​Key Concepts

​Creating a Key

​Managing Keys

​Permissions

​Next Steps

Authentication

Key Concepts

Creating a Key

Managing Keys

Permissions

Next Steps