Authentication

Learn how to authenticate with the Corebill API using API keys.

API Keys

All API requests must include an API key in the Authorization header using the Bearer scheme.

bashBash

 1Authorization: Bearer sk_live_your_api_key

API keys can be generated from the Corebill dashboard under Organization > Developers.

Using the SDK

The SDK handles authentication automatically. Pass your API key when initializing the client:

typescriptTypeScript

 1import Corebill from '@corebill/sdk';
 2
 3const corebill = new Corebill({
 4  apiKey: 'sk_live_your_api_key',
 5  companyId: 'com_abc123', // optional, sets the default company
 6});
 7
 8// All subsequent calls are authenticated
 9const { data: customers } = await corebill.customers.list();

Key Format

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

texttext

 1sk_live_a1b2c3d4e5f6g7h8i9j0...

The token is shown only once at creation time. After that you'll only see the key_prefix (the first 10 characters). If you lose it, revoke the key and create a new one.

Permission Levels

Each API key has one of three hierarchical permission levels:

Level	Description	Allowed operations
`read`	Read-only access	`GET` requests only
`write`	Read + write access	`GET`, `POST` requests
`admin`	Full access	All methods including `DELETE`

Permissions are hierarchical: admin includes all write permissions, and write includes all read permissions. Choose the lowest level that lets your integration work. Most production integrations only need write.

Creating a Key

API keys are created from the dashboard:

Sign in to app.corebill.io
Go to Developers > API Keys
Click New API Key
Pick a name, a company, and a permission level
Copy the sk_... token immediately -- you won't see it again

Treat keys like passwords. Never commit them to source control, share them in chat, or paste them into client-side code. Use environment variables and a secrets manager.

Company Context

All endpoints (except GET /companies) require a company_id query parameter. This scopes the request to a specific company within your organization.

Bash

 1# List customers for a specific company
 2curl "https://api.corebill.io/v1/customers?company_id=com_abc123" \
 3  -H "Authorization: Bearer sk_live_your_api_key"

To find your company IDs, use the List Companies endpoint.

Revoking a Key

When a key is compromised or no longer needed, revoke it from the dashboard. Revocation takes effect immediately -- subsequent requests return 401. There is no way to "rotate" a key in place. To rotate, create a new key, switch your deployment over, then revoke the old one.

Last-Used Tracking

Every successful request updates the last_used_at timestamp on the key. Use this in the dashboard to spot keys that aren't being used and revoke them.

Authentication Errors

Status	Error	Description
`401`	Missing Authorization header	No API key provided
`401`	Invalid API key	Key doesn't exist or is malformed
`401`	API key is disabled	Key has been deactivated
`403`	Insufficient permissions	Key doesn't have the required permission level

jsonJSON

 1{
 2  "error": "Insufficient permissions. Write access required."
 3}

Audit Trail

Every API request is recorded in api_logs with the originating key, method, path, status, duration, IP, and user-agent. You can review the logs from the Developers > Events section of the dashboard.

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

Quickstart Customers