Authentication

All API requests require authentication. Databuddy supports two authentication methods: API keys for server-side integrations and session cookies for browser-based apps.

API Key Authentication

Use your API key in the x-api-key header:

curl -H "x-api-key: dbdy_your_api_key_here" \
https://api.databuddy.cc/v1/query/websites

Alternatively, use Bearer token format:

curl -H "Authorization: Bearer dbdy_your_api_key_here" \
https://api.databuddy.cc/v1/query/websites

Getting an API Key

Go to Dashboard → Organization Settings → API Keys
Click Create API Key
Enter a descriptive name (e.g., "Production Server", "CI Pipeline")
Select the required scopes
Optionally restrict access to specific websites
Copy and securely store your key — it won't be shown again

Security Note: Store API keys securely. Never commit them to version control or expose them in client-side code.

API Key Scopes

Scopes control what actions an API key can perform:

Scope	Permission
`read:data`	Query analytics data and list accessible websites — covers `POST /v1/query`, `POST /v1/query/compile`, `POST /v1/query/custom`, and `GET /v1/query/websites`
`track:events`	Send custom events via `POST /track`
`read:links`	Read short links and their analytics
`write:links`	Create, update, and delete short links
`manage:websites`	Create, update, and delete websites
`manage:flags`	Manage feature flags and targeting rules
`manage:config`	Integration config and organization settings

Most integrations only need read:data. Add track:events if you also send events server-side.

Access Levels

API keys can have two access levels:

Global Access

Access all websites in your account or organization. Best for:

Internal dashboards
Automated reporting
Organization-wide analytics

Website-Specific Access

Access only specified websites. Best for:

Third-party integrations
Client-specific keys
Least-privilege security

Browser-based applications using the Databuddy dashboard session can authenticate automatically via cookies. This works when:

Users are logged into the Databuddy dashboard
Requests include credentials: 'include'
Requests originate from *.databuddy.cc domains

fetch('https://api.databuddy.cc/v1/query/websites', {
credentials: 'include'
})

Choosing an Authentication Method

Use Case	Recommended Method
Server-to-server integration	API Key (`x-api-key`)
CI/CD pipelines	API Key (`x-api-key`)
Custom dashboards (server-side)	API Key (`x-api-key`)
Browser apps on your domain	Session Cookie
Third-party applications	API Key with limited scope

Authentication Errors

Error Code	Meaning
`AUTH_REQUIRED`	No API key or session provided
`ACCESS_DENIED`	Valid auth but no access to requested resource
`INVALID_API_KEY`	API key is invalid, expired, or revoked
`INSUFFICIENT_SCOPE`	API key lacks required scope

Example error response:

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

Best Practices

Use environment variables for API keys in code
Rotate keys regularly — especially if team members leave
Use minimal scopes — only request permissions you need
Set expiration dates for temporary integrations
Monitor usage — check API key activity in the dashboard