# auth.md

The Databuddy MCP server accepts OAuth sign-in. MCP clients that support MCP authorization with Client ID Metadata Documents, such as Claude and Claude Code, connect to https://api.databuddy.cc/v1/mcp with no key: the user signs in to Databuddy, picks one organization and its websites, and approves the permissions the connection may use. The user's organization role still limits access. Discovery starts from the 401 challenge, which points at https://api.databuddy.cc/.well-known/oauth-protected-resource. Dynamic client registration is not supported.

The REST API and other MCP clients, including Cursor and Windsurf, use scoped API keys. Create a key for the organization in https://app.databuddy.cc/organizations/settings#api-keys, choose the smallest scope set needed, and store it securely.

## Use the credential

Send the API key on every REST API request, and on every MCP request from clients that do not sign in:

```bash
curl -H "x-api-key: $DATABUDDY_API_KEY" https://api.databuddy.cc/v1/query/websites
curl -H "Authorization: Bearer $DATABUDDY_API_KEY" https://api.databuddy.cc/v1/query/websites
```

For MCP clients:

```json
{
  "mcpServers": {
    "databuddy": {
      "type": "http",
      "url": "https://api.databuddy.cc/v1/mcp",
      "headers": { "x-api-key": "dbdy_your_api_key_here" }
    }
  }
}
```

## Errors

REST API errors are JSON objects with `success: false`, an error `code`, a human-readable `error`, and where available a `fix` or `hint`. A 401 means the credential is missing or invalid. A 403 means the credential exists but lacks the requested organization or scope.

MCP works differently. Tools that the key's scopes or the approved OAuth permissions do not cover are left out of `tools/list`, and calling one returns a JSON-RPC `-32602` (invalid params) error that names the scopes the tool needs; reconnect with those permissions or use a key that has them. A credential that covers no tools gets `-32601` for every tool call. Tool failures return a result with `isError: true` and `error.code`, such as `unauthorized` for a website or record the credential cannot reach. A missing, expired, or revoked credential returns 401 with a JSON-RPC error and a `WWW-Authenticate` header.

## Revocation

Revoke API keys from https://app.databuddy.cc/organizations/settings#api-keys. Users disconnect OAuth apps from https://app.databuddy.cc/settings/account under Connected apps. Agents should stop using a credential immediately after revocation or any repeated 401 response.

## API key scopes

- `read:data`
- `track:events`
- `read:links`
- `write:links`
- `read:monitors`
- `write:monitors`
- `read:status_pages`
- `write:status_pages`
- `manage:websites`
- `manage:flags`
- `manage:config`

## MCP OAuth scopes

MCP OAuth sign-in grants only these scopes. The consent screen drops any other scope a client requests.

- `read:data`
- `manage:websites`
- `manage:flags`
- `read:links`
- `write:links`