Skip to main content

​
API Keys

The CommodityAI API uses API keys for authentication. All API requests must include your API key in the request headers.

​
Getting Your API Key

  1. Log in to your CommodityAI dashboard
  2. Navigate to Settings → API Keys
  3. Click Generate New API Key
  4. Copy and securely store your API key
Keep your API keys secure! Do not share them in publicly accessible areas such as GitHub repositories, client-side code, or logs.

​
Authentication Header

Include your API key in the Authorization header of every request: 
curl -X GET "https://app.commodityai.com/api/v1/sources/123e4567-e89b-12d3-a456-426614174000/records?limit=10" \
  -H "Authorization: Bearer cai_live_your_api_key_here"

​
Request Format

All API requests should:
  • Use HTTPS
  • Include the Authorization header with your API key
  • Use query parameters for filtering and pagination

​
Example Request

curl -X GET "https://app.commodityai.com/api/v1/sources/123e4567-e89b-12d3-a456-426614174000/records?limit=100&created_at[gte]=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer cai_live_1234567890abcdef"

​
Company Scope

All API operations are automatically scoped to your company. You can only access:
  • Source record definitions and records that belong to your company
  • Custom object definitions and records that belong to your company
This scoping happens automatically through your API key - no additional parameters needed.

​
API Key Types

CommodityAI provides two types of API keys:
  • Live Keys (cai_live_...): Access production data
  • Test Keys (cai_test_...): Access test environment data (coming soon)
Currently, only live keys are available. Use them to access your production data via the API.

​
Error Responses

When authentication fails, you’ll receive a 401 Unauthorized response: 
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}
Common authentication errors:
Status CodeErrorDescription
401UnauthorizedInvalid or missing API key
403ForbiddenAPI key lacks required permissions
429Too Many RequestsRate limit exceeded

​
API Key Management

​
Security Best Practices

  • Rotate regularly: Generate new API keys periodically
  • Use environment variables: Store API keys in environment variables, not in code
  • Separate keys for environments: Use different API keys for development, staging, and production
  • Monitor usage: Review API key usage in the dashboard regularly

​
Revoking API Keys

To revoke an API key:
  1. Go to Settings → API Keys
  2. Click Revoke next to the key you want to disable
  3. Update any applications using that key with a new one
Revoking an API key immediately invalidates it. Any applications using the revoked key will start receiving 401 Unauthorized errors.

​
Rate Limits

API keys are subject to rate limits to ensure fair usage and system stability. See Rate Limits for detailed information about request limits and how to handle rate limiting responses.