The CockroachDB Cloud API uses bearer token authentication. Each request requires a secret key associated with a service account that inherits the account’s permissions.
Creating API Keys
To create an API key:
- Navigate to the CockroachDB Cloud Console
- Go to Organization Settings > API Access
- Click Create API Key
- Select a service account or create a new one
- Assign appropriate roles to the service account
- Copy and securely store the generated secret key
The secret key is only displayed once during creation. Store it securely - you cannot retrieve it later. If lost, you must create a new API key.
Service Account Roles
Service accounts can be assigned the following roles:
Full access to all cluster operations, including create, update, delete, and billing
Can create and delete clusters, but cannot modify existing clusters
Can view and modify existing clusters, but cannot create or delete them
Can manage cluster maintenance windows and operational settings
Can view invoices and billing information
Making Authenticated Requests
Include your secret key in the Authorization header using the Bearer authentication scheme:
curl --request GET \
--url https://cockroachlabs.cloud/api/v1/clusters \
--header "Authorization: Bearer {secret_key}"
curl --request GET \
--url https://cockroachlabs.cloud/api/v1/clusters \
--header "Authorization: Bearer {secret_key}" \
--header "Cc-Version: 2024-09-16"
{secret_key} with your actual API secret key.
Bearer token for authenticationFormat: Bearer {secret_key}
API version in YYYY-MM-DD format (e.g., 2024-09-16)Always specify this header to ensure API stability
Media type of the request body (e.g., application/json)Required for POST, PUT, and PATCH requests
Authentication Errors
401 Unauthorized
Occurs when:
- The secret key is missing or invalid
- The secret key has been revoked
- The service account has been deleted
{
"code": 16,
"message": "unauthenticated",
"details": []
}
403 Forbidden
Occurs when:
- The service account lacks required permissions
- The requested resource is not accessible
{
"code": 7,
"message": "permission denied",
"details": []
}
429 Rate Limited
Occurs when you exceed 10 requests per second:
{
"code": 8,
"message": "rate limit exceeded",
"details": []
}
Retry-After header indicating when you can retry the request.
Security Best Practices
Store Keys Securely
Never commit API keys to version control. Use environment variables or secret management systems.export COCKROACH_API_KEY="your-secret-key-here"
Use Least Privilege
Assign service accounts the minimum permissions required for their tasks.
Rotate Keys Regularly
Create new API keys periodically and revoke old ones.
Monitor API Usage
Track API calls through audit logs to detect unauthorized access.
Example: Complete Authenticated Request
Here’s a complete example of an authenticated request to list all clusters:
curl --request GET \
--url 'https://cockroachlabs.cloud/api/v1/clusters' \
--header 'Authorization: Bearer CC0eJzA1xwg2p9a5CrDB4kLmNoPQRsT7uvWXYZ...' \
--header 'Cc-Version: 2024-09-16' \
--header 'Accept: application/json'
{
"clusters": [
{
"id": "f9b6f5e4-3c2b-4a1d-9e8f-7c6b5a4d3e2f",
"name": "production-cluster",
"plan": "STANDARD",
"provider": "GCP",
"state": "CREATED"
}
],
"pagination": null
}
Testing Your Authentication
To verify your API key is working correctly, make a simple GET request:
curl --request GET \
--url https://cockroachlabs.cloud/api/v1/clusters \
--header "Authorization: Bearer {secret_key}" \
--header "Cc-Version: 2024-09-16" \
--verbose