API Keys

TL;DR

• Generate keys in the dashboard Settings → API Keys
• Use either Authorization: Bearer <key> or x-api-key: <key>
• Scopes: read:data, write:data, read:experiments, track:events, admin:apikeys, read:analytics, write:custom-sql, read:export, write:otel, admin:users, admin:organizations, admin:websites, rate:standard, rate:premium, rate:enterprise
• Access can be global or scoped to a resource like a specific website
• For private websites, include website_id and ensure the key has read:data
• Rotate and revoke keys in the dashboard; only the prefix/start should be shared/logged

What is an API key?

An API key authenticates server-to-server calls to Databuddy. It supports fine-grained scopes and optional resource scoping to enforce least-privilege access.

Create a key

1. Open the dashboard → Settings → API Keys
2. Click “Create API Key”
3. Choose a name, optional organization, scopes, and resource access
4. Copy the secret immediately (it’s only shown once)

We only display the prefix and first characters (start) later for identification. Never share the full secret.

Use your key

You can authenticate with either header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.databuddy.cc/v1/websites/{website_id}/analytics"

curl -H "x-api-key: YOUR_API_KEY" \
"https://api.databuddy.cc/v1/websites/{website_id}/analytics"

Notes:

• For private websites, include the website_id query or path parameter and ensure the key has read:data for that site.
• For public websites, website_id may be optional depending on the endpoint semantics.

Scopes

Data Access Scopes

• read:data: Basic read access to analytics data
• write:data: Write or modify analytics data (server-side ingestion)
• read:analytics: Advanced analytics access with custom queries and exports
• read:export: Access to data export functionality
• write:custom-sql: Execute custom SQL queries against analytics database

Feature-Specific Scopes

• read:experiments: Read A/B tests and feature flags
• track:events: Send tracking events and custom events
• write:otel: Authorize OpenTelemetry tracking and metrics

Administrative Scopes

• admin:apikeys: Create, update, rotate, revoke API keys
• admin:users: User management operations
• admin:organizations: Organization management operations
• admin:websites: Website management operations

Rate Limiting Scopes

• rate:standard: Standard rate limits (default)
• rate:premium: Higher rate limits for premium usage
• rate:enterprise: Enterprise-level rate limits

Grant only what you need. Prefer resource-scoped access where possible.

Resource access

Access can be scoped to different resource types:

• global: Applies to all resources
• website: Applies to a specific website (use the website_id in requests)
• analytics_data: Analytics events and metrics data
• error_data: JavaScript errors and exceptions
• web_vitals: Core Web Vitals performance metrics
• custom_events: Custom event tracking data
• export_data: Data export operations

Example: a key with read:data on a single website can read analytics only for that website, not others. A key with read:analytics scoped to analytics_data can access detailed analytics but not error data.

Errors

Authentication/authorization failures return structured errors:

{
  "success": false,
  "error": "Authentication required",
  "code": "AUTH_REQUIRED"
}

{
  "success": false,
  "error": "Insufficient permissions",
  "code": "FORBIDDEN"
}

Rotation and revocation

• Rotate to generate a new secret for the same key (update your servers immediately)
• Revoke to immediately disable a key (cannot be undone; create a new one if needed)

Actions are available in the dashboard under each key’s detail view.

Rate limits

All API endpoints are rate-limited. See the Rate Limits section in the API Reference. Responses include standard X-RateLimit-* headers where applicable.

Audit Logging

All API key usage is logged for security and compliance:

• Authentication events: Successful and failed key usage
• Scope resolution: What permissions were checked and granted
• Resource access: Which data resources were accessed
• Administrative actions: Key creation, rotation, and revocation

Logs include IP addresses, user agents, and timestamps for security monitoring.

Best practices

• Treat API keys like passwords; don't commit them to source control
• Use environment variables or secret managers
• Share only the prefix and start snippet for identification
• Use least-privilege scopes and resource scoping
• Rotate keys periodically and revoke unused keys
• Monitor audit logs for suspicious activity
• Use resource-scoped keys for better security