Authentication

Authentication

To authenticate with the OpenPanel API, you need to use your clientId and clientSecret. Different API endpoints may require different access levels:

• Track API: Default client works with write mode
• Export API: Requires read or root mode
• Insights API: Requires read or root mode
• Manage API: Requires root mode only

The default client (created with a project) has write mode and does not have access to the Export, Insights, or Manage APIs. You'll need to create additional clients with appropriate access levels.

Headers

Include the following headers with your API requests:

• openpanel-client-id: Your OpenPanel client ID
• openpanel-client-secret: Your OpenPanel client secret

Example

curl 'https://api.openpanel.dev/insights/{projectId}/metrics' \
  -H 'openpanel-client-id: YOUR_CLIENT_ID' \
  -H 'openpanel-client-secret: YOUR_CLIENT_SECRET'

Security Best Practices

1. Store credentials securely: Never expose your clientId and clientSecret in client-side code
2. Use HTTPS: Always use HTTPS to ensure secure communication
3. Rotate credentials: Regularly rotate your API credentials
4. Limit access: Use the minimum required access level for your use case

Error Responses

If authentication fails, you'll receive a 401 Unauthorized response:

{
  "error": "Unauthorized",
  "message": "Invalid client credentials"
}

Common authentication errors:

• Invalid client ID or secret
• Client doesn't have required permissions (e.g., trying to access Manage API with a non-root client)
• Malformed client ID (must be a valid UUIDv4)
• Client type mismatch (e.g., write client trying to access Export API)

Client Types

OpenPanel supports three client types with different access levels:

Note: Root clients have organization-wide access and can manage all resources. Use root clients carefully and store their credentials securely.

Rate Limiting

The API implements rate limiting to prevent abuse. Rate limits vary by endpoint:

• Track API: Higher limits for event tracking
• Export/Insights APIs: 100 requests per 10 seconds
• Manage API: 20 requests per 10 seconds

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Implement exponential backoff for retries.

Remember to replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your actual OpenPanel API credentials.