Skip to main content

​
Overview

The Composite Analytics API uses API keys to authenticate requests. You can view and manage your API keys in the Analytics Dashboard.
​
Public Keys
string
Start with pk_ and are safe to use in client-side code (browsers, mobile apps)

​
Authentication Methods

​
SDK Authentication

The easiest way to authenticate is using the Composite SDK: 
// Use public key in browsers
import composite from '@composite-inc/composite-js';

await composite.init({
  apiKey: 'pk_live_abc123...'  // Public key
});

​
HTTP Header Authentication

For direct API calls, include your API key in the Authorization header: 
curl -X POST https://prod.alb.us.api.composite.com/v1/events \
  -H "Authorization: Bearer pk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "page_viewed", "properties": {}}'

​
API Key Types

​
Public Keys (pk_)

Public keys have limited permissions suitable for client-side use:
PermissionAllowed
Send events✅
Send session recordings✅
Identify users✅
Read own user profile✅
Read project configuration✅
Access admin endpoints❌
Read other users’ data❌
Modify project settings❌

​
Rate Limiting

API keys are subject to rate limits:
Key TypeRequests/SecondRequests/DayBurst Limit
Public1,000100,000,00010,000
Secret10,0001,000,000,000100,000

​
Rate Limit Headers

The API returns rate limit information in response headers: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

​
Handling Rate Limits

Implement exponential backoff when rate limited: 
async function apiCall(url, options, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      // Rate limited - wait and retry
      const retryAfter = response.headers.get('Retry-After') || 2 ** i;
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}

​
Troubleshooting

This error means your API key is invalid or missing:
  • Check that the key is correctly copied
  • Ensure you’re using the right key type (public vs secret)
  • Verify the key hasn’t been revoked
  • Check that the Authorization header is properly formatted
Your API key doesn’t have permission for this operation:
  • Public keys cannot access admin endpoints
  • Check the key’s permission settings in the dashboard
  • Use a secret key for server-side operations
You’ve exceeded the rate limit:
  • Implement exponential backoff
  • Batch your requests when possible
  • Consider upgrading your plan for higher limits
  • Check the Retry-After header for when to retry
Common issues and solutions:
  • Ensure environment variables are set in production
  • Check for typos or extra whitespace in the key
  • Verify the key is for the correct environment (test vs live)
  • Confirm the key has the necessary permissions

​
Next Steps

Events API

Learn about the Events API endpoints

SDK Quickstart

Get started with the SDK