Public API Authentication
Authenticate requests with project-scoped API keys, scopes, rate limits, and standard error responses.
Public API requests authenticate with a project-scoped API key. Send the key in the Authorization header as a bearer token:
Authorization: Bearer YOUR_PUBLIC_API_KEYKeep API keys secret. Use them from trusted server-side environments, not from browser code or mobile apps.
Manage keys
Open your project's API page in the dashboard to create, revoke, and review API keys. Choose the narrowest preset for each integration:
| Preset | Scopes |
|---|---|
| Reporting read key | reporting:read |
| Conversion write key | conversions:write |
| Full project API key | reporting:read, activity:read, conversions:write |
The API page also lists connected MCP clients and managed MCP-backed keys. Revoking either the MCP connection or its managed key disables that client's access.
Scopes
Each API key has one or more scopes. Scopes limit what that key can do:
| Scope | Allows |
|---|---|
reporting:read | Read reporting metrics and conversion journeys. |
activity:read | Read unconverted visitor activity. |
conversions:write | Create conversion events. |
If a key is valid but does not include the scope required by an endpoint, the request fails with a missing_scope error.
Rate limits
Public API requests are rate limited per API key. Reporting reads and conversion writes may have different limits. Invalid authentication attempts may also be limited by client address.
When a limit is exceeded, the API returns 429 Too Many Requests with a rate_limit_exceeded error code. If you have multiple integrations, create separate keys for each integration so permissions remain isolated.
Error envelope
Errors use a consistent JSON envelope:
{
"error": {
"code": "invalid_request",
"message": "The request could not be processed.",
"request_id": "req_..."
}
}The code field is stable and suitable for programmatic handling. The message field is human-readable and may change. Some errors may include a details object with additional fields that explain how to fix the request.
Common error codes include:
| Code | Meaning |
|---|---|
invalid_api_key | The bearer token is missing, invalid, or no longer active. |
missing_scope | The key does not have the scope required for the endpoint. |
invalid_request | The request body or query string is malformed. |
invalid_date_range | The reporting date filters are invalid. |
invalid_cursor | The pagination cursor is invalid or expired. |
rate_limit_exceeded | The request exceeded an API rate limit. |
not_found | The requested resource was not found. |
validation_failed | One or more fields failed validation. |
internal_error | The API could not complete the request. Retry later. |
See the API Reference for endpoint-specific status codes and schemas.