Skip to main content

​
API Keys

All API requests must include an API key in the Authorization header using the Bearer scheme. 
Authorization: Bearer sk_live_your_api_key
API keys can be generated from the Corebill dashboard under Organization > Developers.

​
Key Format

API keys follow the format sk_ followed by a unique identifier: 
sk_live_a1b2c3d4e5f6g7h8i9j0

​
Permission Levels

Each API key has one of three hierarchical permission levels:
LevelDescriptionAllowed operations
readRead-only accessGET requests only
writeRead + write accessGET, POST, PATCH requests
adminFull accessAll methods including DELETE
Permissions are hierarchical: admin includes all write permissions, and write includes all read permissions.

​
Company Context

All endpoints (except GET /companies) require a company_id query parameter. This scopes the request to a specific company within your organization. 
# List customers for a specific company
curl "https://api.corebill.io/v1/customers?company_id=com_abc123" \
  -H "Authorization: Bearer sk_live_your_api_key"
To find your company IDs, use the List Companies endpoint.

​
Error Responses

Authentication errors return standard HTTP status codes:
StatusErrorDescription
401Missing Authorization headerNo API key provided
401Invalid API keyKey doesn’t exist or is malformed
401API key is disabledKey has been deactivated
403Insufficient permissionsKey doesn’t have the required permission level
{
  "error": "Insufficient permissions. Write access required."
}

​
Security Recommendations

  • Store API keys in environment variables, never in source code
  • Use the minimum permission level required for your integration
  • Rotate keys periodically from the dashboard
  • Use separate keys for development and production environments