Authentication

Overview

The Composite Analytics API uses API keys to authenticate requests. You can view and manage your API keys in the Analytics Dashboard. There are two types of API keys:

Public Keys

string

Start with pk_ and are safe to use in client-side code (browsers, mobile apps)

Secret Keys

string

Start with sk_ and should only be used in server-side applications

Never expose your secret keys in client-side code, public repositories, or any place accessible to end users. Secret keys have full API access and can perform administrative actions.

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": {}}'

Query Parameter Authentication

As an alternative, you can pass the API key as a query parameter:

curl -X POST "https://prod.alb.us.api.composite.com/v1/events?api_key=pk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"name": "page_viewed"}'

Header authentication is preferred over query parameters for security reasons, as query parameters may be logged in server access logs.

API Key Types

Public Keys (`pk_`)

Public keys have limited permissions suitable for client-side use:

Permission	Allowed
Send events	✅
Send session recordings	✅
Identify users	✅
Read own user profile	✅
Read project configuration	✅
Access admin endpoints	❌
Read other users’ data	❌
Modify project settings	❌

Secret Keys (`sk_`)

Secret keys have full API access:

Permission	Allowed
All public key permissions	✅
Read all events	✅
Read all users	✅
Export data	✅
Modify project settings	✅
Manage team members	✅
Access billing	✅
Delete data	✅

API Key Management

Creating API Keys

Log in to the Analytics Dashboard
Navigate to Settings → API Keys
Click “Create New Key”
Choose key type (Public or Secret)
Add a descriptive label
Set permissions (for secret keys)
Copy the key immediately (it won’t be shown again)

Key Rotation

Regularly rotate your API keys for security:

Create new key

Generate a replacement key in the dashboard

Update applications

Deploy your applications with the new key

Verify functionality

Confirm all services are using the new key

Revoke old key

Delete the old key from the dashboard

Revoking Keys

To immediately revoke a key:

curl -X DELETE https://prod.alb.us.api.composite.com/v1/api-keys/{key_id} \
  -H "Authorization: Bearer sk_live_admin_key..."

Environment Configuration

Development vs Production

Use different keys for different environments:

// config.js
const config = {
  development: {
    apiKey: 'pk_test_abc123...',
    apiHost: 'https://api-dev.composite.com'
  },
  staging: {
    apiKey: 'pk_staging_def456...',
    apiHost: 'https://api-staging.composite.com'
  },
  production: {
    apiKey: 'pk_live_ghi789...',
    apiHost: 'https://prod.alb.us.api.composite.com'
  }
};

const environment = process.env.NODE_ENV || 'development';

await composite.init({
  apiKey: config[environment].apiKey,
  apiHost: config[environment].apiHost
});

Environment Variables

Store API keys in environment variables:

# Never commit this file
COMPOSITE_PUBLIC_KEY=pk_live_abc123...
COMPOSITE_SECRET_KEY=sk_live_xyz789...

CI/CD Configuration

Configure keys in your CI/CD pipeline:

GitHub Actions
Vercel
Netlify
Docker

# .github/workflows/deploy.yml
env:
  COMPOSITE_PUBLIC_KEY: ${{ secrets.COMPOSITE_PUBLIC_KEY }}
  COMPOSITE_SECRET_KEY: ${{ secrets.COMPOSITE_SECRET_KEY }}

Rate Limiting

API keys are subject to rate limits:

Key Type	Requests/Second	Requests/Day	Burst Limit
Public	100	1,000,000	1,000
Secret	1,000	10,000,000	10,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');
}

Security Best Practices

Use Environment Variables

Never hardcode API keys in your source code

Rotate Keys Regularly

Change your API keys every 90 days

Limit Key Permissions

Use public keys when possible, limit secret key scope

Monitor Key Usage

Track API key usage in the dashboard

Security Checklist

Store keys in environment variables
Use public keys in client-side code
Keep secret keys on secure servers only
Rotate keys regularly
Monitor for unusual API activity
Use HTTPS for all API calls
Implement proper error handling
Never log API keys

OAuth 2.0 (Coming Soon)

We’re working on OAuth 2.0 support for more secure third-party integrations:

// Future OAuth implementation
const client = new CompositeOAuth({
  clientId: 'your_client_id',
  clientSecret: 'your_client_secret',
  redirectUri: 'https://app.example.com/callback'
});

const authUrl = client.getAuthorizationUrl({
  scope: ['read:events', 'write:events'],
  state: 'random_state_string'
});

Troubleshooting

401 Unauthorized Error

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

403 Forbidden Error

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

429 Too Many Requests

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

API Key Not Working in Production

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

API Key Scopes

When creating secret keys, you can limit their scope:

Scope	Description
`events:write`	Send events and session data
`events:read`	Read events and sessions
`users:write`	Create and update user profiles
`users:read`	Read user profiles
`projects:write`	Modify project settings
`projects:read`	Read project configuration
`team:write`	Manage team members
`billing:read`	View billing information
`billing:write`	Modify billing settings

Example creating a scoped key via API:

curl -X POST https://prod.alb.us.api.composite.com/v1/api-keys \
  -H "Authorization: Bearer sk_live_admin..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Deploy Key",
    "type": "secret",
    "scopes": ["events:write", "users:write"],
    "expires_at": "2024-12-31T23:59:59Z"
  }'

Next Steps

Events API

Learn about the Events API endpoints

SDK Quickstart

Get started with the SDK

Rate Limits

Understanding rate limits

Webhooks

Set up webhook integrations

​Overview

​Authentication Methods

​SDK Authentication

​HTTP Header Authentication

​Query Parameter Authentication

​API Key Types

​Public Keys (pk_)

​Secret Keys (sk_)

​API Key Management

​Creating API Keys

​Key Rotation

​Revoking Keys

​Environment Configuration

​Development vs Production

​Environment Variables

​CI/CD Configuration

​Rate Limiting

​Rate Limit Headers

​Handling Rate Limits

​Security Best Practices

Use Environment Variables

Rotate Keys Regularly

Limit Key Permissions

Monitor Key Usage

​Security Checklist

​OAuth 2.0 (Coming Soon)

​Troubleshooting

​API Key Scopes

​Next Steps

Events API

SDK Quickstart

Rate Limits

Webhooks

Overview

Authentication Methods

SDK Authentication

HTTP Header Authentication

Query Parameter Authentication

API Key Types

Public Keys (`pk_`)

Secret Keys (`sk_`)

API Key Management

Creating API Keys

Key Rotation

Revoking Keys

Environment Configuration

Development vs Production

Environment Variables

CI/CD Configuration

Rate Limiting

Rate Limit Headers

Handling Rate Limits

Security Best Practices

Security Checklist

OAuth 2.0 (Coming Soon)

Troubleshooting

API Key Scopes

Next Steps