Protected API operations require authentication. Operations explicitly documented as public, such as query-type discovery and public status-page reads, do not. Databuddy supports API keys for server-side integrations, session cookies for browser-based apps, and Databuddy account sign-in (OAuth) for MCP clients such as Claude and Claude Code.

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.

Agent auth discovery

AI agents can discover Databuddy authentication without scraping this page:

Resource	URL
auth.md walkthrough	`https://www.databuddy.cc/auth.md`
API catalog	`https://api.databuddy.cc/.well-known/api-catalog`
MCP OAuth metadata	`https://api.databuddy.cc/.well-known/oauth-protected-resource`

The MCP server accepts OAuth sign-in: clients that support MCP authorization with Client ID Metadata Documents, such as Claude and Claude Code, connect to https://api.databuddy.cc/v1/mcp without a key and the user approves access in Databuddy. See the MCP server docs. The REST API and other MCP clients, including Cursor and Windsurf, use scoped API keys sent with x-api-key or Authorization: Bearer.

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`, and `GET /v1/query/websites`
`track:events`	Send custom events via `POST /track`
`read:links`	Read short links via the link management routes. Link analytics via `POST /v1/query` with `link_id` instead requires `read:data` on a key with global access
`write:links`	Create, update, and delete short links
`read:monitors`	Read uptime monitors and their analytics; also unlocks `POST /v1/query` for uptime query types
`write:monitors`	Create, update, pause, resume, and delete uptime monitors
`read:status_pages`	Read status pages, incidents, and monitor visibility
`write:status_pages`	Manage status pages, incidents, and monitor visibility
`manage:websites`	Create, update, publish, and delete websites. MCP uses it for goals, funnels, annotations, and investigation replies
`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
Claude and Claude Code (MCP)	Databuddy account sign-in (OAuth)
Cursor, Windsurf, and other MCP clients	API key (`x-api-key`)

Authentication errors

Error code	Meaning
`AUTH_REQUIRED`	The operation needs authentication and none was accepted
`ACCESS_DENIED`	Authentication succeeded but the key cannot access the resource or operation

Example error response:

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

Best practices

Use environment variables for API keys in code
Rotate keys regularly, especially when 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

Authentication