Authentication
Every request to the Capx API must be authenticated with a secret API key. This page covers how to obtain, scope, rotate, and use your keys securely.
Getting API Keys
API keys are created in the Capx Casa dashboard under Settings > API Keys. Each key is tied to a specific company and can be scoped to limit the operations it can perform. When you create a key, it is displayed exactly once. Copy it immediately and store it in a secure location such as a secrets manager or encrypted environment variable.
Key Format
All Capx API keys follow a predictable format so you can identify the key type and environment at a glance.
| Prefix | Environment | Usage |
|---|---|---|
| capx_sk_live_ | Production | Live API access with real credit consumption |
| capx_sk_test_ | Sandbox | Testing with no credit charges or side effects |
Keys are 56 characters in total. The prefix is followed by 40 alphanumeric characters.
Key Scoping
When creating a key, you can restrict its permissions to specific resource types. Scoped keys follow the principle of least privilege, reducing exposure if a key is compromised.
| Scope | Allows |
|---|---|
| companies:read | List and retrieve companies |
| companies:write | Create, update, pause, resume, and delete companies |
| agents:read | List and retrieve agents, activity, and costs |
| agents:write | Add, update, remove, and wake agents |
| tasks:read | List and retrieve tasks |
| tasks:write | Create, update, approve, and reject tasks |
| playbooks:read | List and retrieve playbooks and runs |
| playbooks:write | Create playbooks and trigger runs |
| activity:read | Read activity feed and cost data |
| * | Full access (default for new keys) |
Key Rotation
You can have up to 5 active keys per company at any time. To rotate a key without downtime, create a new key, update your application to use it, and then revoke the old key. Revoked keys are rejected immediately and cannot be reinstated.
Create a new key
In the Casa dashboard, go to Settings > API Keys > New Key.
Deploy the new key
Deploy the new key to your application via environment variables.
Verify traffic
Verify traffic is flowing with the new key by checking the dashboard logs.
Revoke the old key
In Settings > API Keys, revoke the old key. It is rejected immediately.
Using the Bearer Token
Include your API key in the Authorization header of every request. The key must be prefixed with "Bearer" followed by a space.
curl https://api.capx.ai/v1/companies \ -H "Authorization: Bearer capx_sk_live_abc123def456ghi789jkl012mno345pq"
Authentication Errors
When authentication fails, the API returns one of the following error codes.
| Status | Code | Cause |
|---|---|---|
| 401 | unauthorized | No Authorization header, malformed token, or revoked key |
| 403 | forbidden | Valid key but insufficient scope for the requested operation |
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Invalid or missing API key.",
"docs": "https://capx.ai/docs/api/authentication"
}
}