Authentication
API keys, permissions, and test mode.
All API requests require authentication using an API key passed in the Authorization header.
API Keys
Header Format
Include your API key in every request:
Authorization: Bearer cb_live_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxKey Types
| Prefix | Type | Description |
|---|---|---|
cb_live_ | Production | Billed requests, real market data |
cb_test_ | Test | Free requests, mock data for development |
Creating a Key
- Go to the Developer Console
- Click Create Key
- Name your key (e.g., "Production", "Staging", "Local Dev")
- Select the permissions your key needs
- Click Create
- Copy the key immediately — it won't be shown again
Key Security
- Never expose API keys in client-side code or public repositories
- Always call the API from your server, not from browsers
- Use environment variables to store keys
- Rotate keys regularly and revoke unused ones
Permissions
Each API key has specific permissions that determine which endpoints it can access.
| Permission | Required For |
|---|---|
benchmark:basic | POST /benchmark/basic |
benchmark:detailed | POST /benchmark/detailed |
market:read | GET /market |
If you call an endpoint without the required permission, you'll receive:
{
"success": false,
"error": {
"code": "INSUFFICIENT_PERMISSIONS",
"message": "API key lacks required permission: benchmark:detailed"
}
}Updating Permissions
To add or remove permissions:
- Go to the Developer Console
- Find your key in the list
- Click the ... menu and select Edit permissions
- Toggle the permissions you need
- Click Save
Changes take effect immediately.
Test Mode
Keys starting with cb_test_ operate in test mode:
- No credits consumed — Free unlimited requests
- Mock data returned — Realistic but not real market data
- Perfect for development — Test your integration without cost
Test Mode Response
Responses include a test_mode flag:
{
"success": true,
"data": {
"median_rate_per_km": 1.35,
"avg_rate_per_km": 1.38,
"offer_count": 100,
"confidence": "high",
"search_method": "route_stats"
},
"test_mode": true,
"request_id": "test-550e8400-e29b-41d4-a716-446655440000"
}When to Use Test Keys
Use test keys during:
- Local development
- CI/CD pipeline testing
- Integration testing
- Demo environments
Switch to production keys (cb_live_) when you need real market data.
Key Management
Viewing Keys
In the Developer Console, you can see:
- Key name and prefix (first 12 characters)
- Created date
- Last used date
- Enabled/disabled status
- Assigned permissions
For security, the full key is never shown after creation. If you lose a key, revoke it and create a new one.
Disabling Keys
You can temporarily disable a key without revoking it:
- Find the key in the Developer Console
- Toggle the Enabled switch off
Disabled keys return a 401 INVALID_API_KEY error. Re-enable anytime by toggling the switch back on.
Revoking Keys
To permanently delete a key:
- Find the key in the Developer Console
- Click ... → Revoke key
- Confirm the action
Irreversible
Revoked keys cannot be recovered. Any applications using the key will immediately stop working.
Example Integration
// Store your key in an environment variable
const CARGOBLOOM_API_KEY = process.env.CARGOBLOOM_API_KEY;
async function getBenchmark(origin, destination) {
const response = await fetch('https://cargobloom.io/api/v1/benchmark/basic', {
method: 'POST',
headers: {
'Authorization': `Bearer ${CARGOBLOOM_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
origin_country: origin,
dest_country: destination,
}),
});
if (!response.ok) {
const error = await response.json();
throw new Error(error.error?.message || 'API request failed');
}
return response.json();
}import os
import requests
CARGOBLOOM_API_KEY = os.environ['CARGOBLOOM_API_KEY']
def get_benchmark(origin: str, destination: str) -> dict:
response = requests.post(
'https://cargobloom.io/api/v1/benchmark/basic',
headers={
'Authorization': f'Bearer {CARGOBLOOM_API_KEY}',
'Content-Type': 'application/json',
},
json={
'origin_country': origin,
'dest_country': destination,
}
)
response.raise_for_status()
return response.json()package main
import (
"bytes"
"encoding/json"
"net/http"
"os"
)
func getBenchmark(origin, destination string) (map[string]interface{}, error) {
apiKey := os.Getenv("CARGOBLOOM_API_KEY")
payload, _ := json.Marshal(map[string]string{
"origin_country": origin,
"dest_country": destination,
})
req, _ := http.NewRequest("POST",
"https://cargobloom.io/api/v1/benchmark/basic",
bytes.NewBuffer(payload))
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
return nil, err
}
defer resp.Body.Close()
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
return result, nil
}Authentication Errors
| Status | Code | Cause |
|---|---|---|
| 401 | MISSING_API_KEY | No Authorization header provided |
| 401 | INVALID_API_KEY | Key not found, wrong format, or revoked |
| 403 | INSUFFICIENT_PERMISSIONS | Key lacks required permission for endpoint |
See Error Handling for complete error documentation.
Last updated: February 1, 2026