API Key Authentication
All API requests must include an API key in the x-api-key header.
curl -X GET "https://api.bitbybit.studio/customer/open/v1/customers" \
-H "x-api-key: bbb_live_abc123..."
Creating an API Key
- Log in to your bitbybit dashboard
- Navigate to Settings > Developer
- Click Create API Key
- Give it a name and select the scopes (permissions) it needs
- Click Create and copy the key immediately
The raw API key is only shown once at creation time. Store it securely — you won’t be able to retrieve it again.
| Environment | Prefix | Example |
|---|
| Production | bbb_live_ | bbb_live_a1b2c3d4e5f6... |
| Test | bbb_test_ | bbb_test_a1b2c3d4e5f6... |
Scopes
API keys are scoped to specific resources and actions. Available scopes:
| Resource | Actions | Description |
|---|
customers | READ, WRITE, DELETE | Manage customer records |
orders | READ, WRITE | Manage orders |
products | READ, WRITE, DELETE | Manage product catalog |
messages | READ, WRITE | Send and retrieve WhatsApp messages |
READ access to customers can list and get customers, but cannot create or update them.
Key Rotation
To rotate an API key without downtime:
- Go to Settings > Developer
- Click the menu on your active key and select Rotate
- A new key is created and the old key gets a 24-hour grace period
- Update your application with the new key
- The old key automatically stops working after the grace period
IP Whitelisting
You can restrict an API key to specific IP addresses or CIDR ranges. When configured, only requests from those IPs are accepted — all others receive a 403 error.
See IP Whitelisting for setup instructions and supported formats.
Error Responses
| Status | Code | Description |
|---|
| 401 | MISSING_API_KEY | No x-api-key header provided |
| 401 | INVALID_API_KEY | Key is invalid, revoked, or expired |
| 403 | INSUFFICIENT_SCOPE | Key doesn’t have the required scope |
| 403 | IP_NOT_ALLOWED | Request IP is not in the key’s allowlist |
