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 interactive MCP clients such as Claude, Claude Code, Codex, Cursor, and VS 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 Add 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`

Interactive MCP clients, such as Claude, Claude Code, Codex, Cursor, and VS Code, sign in with a Databuddy account over OAuth. The authorization server supports MCP authorization with Client ID Metadata Documents, so these clients connect to https://api.databuddy.cc/v1/mcp without a key, and the user approves an organization, websites, and permissions in Databuddy. Scoped API keys sent with x-api-key or Authorization: Bearer remain the way to authenticate the REST API, and they work on MCP for headless use such as scripts, CI jobs, and custom agents built on an MCP SDK. The MCP server does not accept dashboard session cookies. See the MCP server docs for per-client setup.

API key scopes

Scopes control what actions an API key can perform:

Scope	Permission
`read:data`	Query analytics data, list accessible websites, and read session replays: covers `POST /v1/query`, `POST /v1/query/compile`, `GET /v1/query/websites`, and `POST /replays/*`
`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 allows uptime query types on `POST /v1/query`
`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.

The REST reporting recipe uses only read access and shows how to select a website and verify a complete response before scheduling a report.

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
Interactive MCP clients (Claude, Claude Code, Codex, Cursor, VS Code, ChatGPT)	Databuddy account sign-in (OAuth)
MCP from scripts, CI, and custom agents	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

On this page