API Keys

API keys allow you to authenticate API requests programmatically without using session cookies. API keys are tenant-scoped and support granular permissions via scopes.

Creating an API Key

Via UI

1. Navigate to Admin → API (/admin/api)
2. Click Create Key
3. Configure:
   • Name: Descriptive name for the key (required)
   • Scopes: Select permissions (required)
4. Click Create Key
5. Copy the key immediately - it's shown only once and cannot be retrieved later

Via API

1curl -X POST "https://app.betterdata.co/api/admin/api-keys" \
2  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Production API Key",
6    "scopes": ["inventory:read", "forecast:read"]
7  }'

Response:

1{
2  "apiKey": {
3    "id": "key_123",
4    "name": "Production API Key",
5    "keyPrefix": "bdk_live_ABC123",
6    "last4": "XYZ1",
7    "scopes": ["inventory:read", "forecast:read"],
8    "status": "ACTIVE",
9    "createdAt": "2024-01-01T00:00:00Z"
10  },
11  "plaintextKey": "bdk_live_ABC123_<random>"
12}

Using API Keys

Include the API key in the Authorization header as a Bearer token:

1curl -X GET "https://app.betterdata.co/api/inventory/channel-location?locationId=loc_123&page=1&limit=50" \
2  -H "Authorization: Bearer bdk_live_ABC123_<your-key>" \
3  -H "Content-Type: application/json"

Scopes

API keys support granular permissions via scopes:

Inventory

• inventory:read - Read inventory data
• inventory:write - Create/update inventory

Forecasting

• forecast:read - Read forecasts
• forecast:write - Create/update forecasts

Planning

• planning:read - Read planning data
• planning:write - Create/update plans

Procurement

• procurement:read - Read procurement data
• procurement:write - Create/update purchase orders

Shipping

• shipping:read - Read shipping data
• shipping:write - Create/update shipments

Reports

• reports:read - Read reports

Admin

• admin:read - Read admin data
• admin:write - Admin operations (tenant admin only)

Wildcards

• inventory:* - All inventory operations
• * - All operations (use with caution)

Managing API Keys

List Keys

1curl -X GET "https://app.betterdata.co/api/admin/api-keys" \
2  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Update Key Metadata

1curl -X PATCH "https://app.betterdata.co/api/admin/api-keys/key_123" \
2  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "name": "Updated Name",
6    "scopes": ["inventory:read", "inventory:write"]
7  }'

Revoke Key

1curl -X POST "https://app.betterdata.co/api/admin/api-keys/key_123/revoke" \
2  -H "Authorization: Bearer YOUR_SESSION_TOKEN"

Rotate Key

Create a new key and optionally revoke the old one:

1curl -X POST "https://app.betterdata.co/api/admin/api-keys/key_123/rotate" \
2  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "revokeOld": true
6  }'

Security Best Practices

1. Store securely: Never commit API keys to version control
2. Use environment variables: Store keys in environment variables or secret management systems
3. Rotate regularly: Rotate keys periodically (e.g., every 90 days)
4. Limit scopes: Grant minimum permissions required
5. Set expiration: Use expiration dates for temporary keys
6. Monitor usage: Review API key usage logs regularly
7. Revoke unused keys: Delete keys that are no longer needed

Error Codes

| Code | Status | Description | |------|--------|-------------| | MISSING_AUTHORIZATION | 401 | Authorization header missing | | INVALID_API_KEY | 401 | API key not found or invalid | | REVOKED_API_KEY | 401 | API key has been revoked | | EXPIRED_API_KEY | 401 | API key has expired | | INACTIVE_ORGANIZATION | 403 | Organization is not active | | IP_RESTRICTED | 403 | API key not authorized for this IP | | INSUFFICIENT_SCOPE | 403 | Key lacks required scope |

Example: Get Channel × Location ATP Matrix

1curl -X GET "https://app.betterdata.co/api/inventory/channel-location?locationId=loc_123&page=1&limit=50" \
2  -H "Authorization: Bearer bdk_live_ABC123_<your-key>" \
3  -H "Content-Type: application/json"

This requires the inventory:read scope.