API Keys Endpoint
Manage API keys for programmatic access.
Endpoints#
| Method | Endpoint | Description |
|---|---|---|
GET | /api-keys | List API keys |
POST | /api-keys | Create an API key |
GET | /api-keys/:id | Get API key details |
PATCH | /api-keys/:id | Update an API key |
DELETE | /api-keys/:id | Revoke an API key |
API Key Object#
Loading code block...
Note: The full API key is only returned once when created. Store it securely.
List API Keys#
Loading code block...
Example Request#
Loading code block...
Response#
Loading code block...
Create API Key#
Loading code block...
Request Body#
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Key name (1-100 chars) |
scopes | array | No | Permission scopes (default: all) |
expiresInDays | integer | No | Days until expiration |
Available Scopes#
| Scope | Description |
|---|---|
read:projects | Read project data |
write:projects | Create and update projects |
delete:projects | Delete projects |
read:usage | View usage statistics |
write:usage | Track usage events |
read:subscription | View subscription details |
manage:api-keys | Create and revoke API keys |
invoke:agents | Invoke AI agents |
apply:skills | Apply skill patterns |
Example Request#
Loading code block...
Response#
Loading code block...
Important: The key field contains the full API key. This is the only time it will be shown. Store it securely.
Get API Key#
Loading code block...
Example Request#
Loading code block...
Response#
Returns the API key object (without the full key).
Update API Key#
Loading code block...
Request Body#
| Field | Type | Description |
|---|---|---|
name | string | Key name |
scopes | array | Permission scopes |
Example Request#
Loading code block...
Response#
Returns the updated API key object.
Revoke API Key#
Loading code block...
Example Request#
Loading code block...
Response#
Loading code block...
Key Prefixes#
| Prefix | Environment |
|---|---|
bs_live_ | Production keys |
bs_test_ | Test/development keys |
Test keys can only access test data and have lower rate limits.
Best Practices#
1. Use Minimal Scopes#
Only grant the scopes needed for each key:
Loading code block...
2. Set Expiration for Temporary Keys#
Loading code block...
3. Rotate Keys Regularly#
Create new keys and revoke old ones periodically:
Loading code block...
4. Use Environment Variables#
Loading code block...
Limits#
| Plan | Max Keys |
|---|---|
| Free | 2 |
| Pro | 10 |
| Team | 50 |
| Enterprise | Unlimited |
Errors#
| Code | Description |
|---|---|
key_not_found | API key doesn't exist |
key_limit_exceeded | Maximum keys reached |
invalid_scope | Unknown scope specified |
key_expired | API key has expired |