# auth.md

Databuddy supports agent authentication with scoped API keys. This file is the prose companion to Databuddy's OAuth Protected Resource Metadata at https://api.databuddy.cc/.well-known/oauth-protected-resource. Agents should use the metadata as the source of truth for endpoint URLs and this file for the step-by-step flow.

## 1. Discover

Fetch https://api.databuddy.cc/.well-known/oauth-protected-resource. The protected resource metadata advertises `resource`, `authorization_servers`, `scopes_supported`, and `bearer_methods_supported`. API 401 responses also include `WWW-Authenticate: Bearer resource_metadata="https://api.databuddy.cc/.well-known/oauth-protected-resource"` so agents can recover from a cold unauthenticated probe.

## 2. Pick a method

Databuddy supports API-key credentials for agents. Use `anonymous` only for discovery and sandbox probes. Use `identity_assertion` when an agent provider can present an ID-JAG identity assertion for the user. The machine-readable `agent_auth` block is:

```json
{
  "agent_auth": {
    "register_uri": "https://api.databuddy.cc/agent-auth/register",
    "claim_uri": "https://api.databuddy.cc/agent-auth/claim",
    "revocation_uri": "https://api.databuddy.cc/agent-auth/revoke",
    "skill": "https://www.databuddy.cc/auth.md",
    "identity_types_supported": [
      "anonymous",
      "identity_assertion"
    ],
    "anonymous": {
      "credential_types_supported": [
        "api_key"
      ]
    },
    "identity_assertion": {
      "assertion_types_supported": [
        "urn:ietf:params:oauth:token-type:id-jag"
      ],
      "credential_types_supported": [
        "api_key"
      ]
    }
  }
}
```

## 3. Register

Use `register_uri`: https://api.databuddy.cc/agent-auth/register. Production workspace credentials are created from the Databuddy dashboard at https://app.databuddy.cc/organizations/settings#api-keys. Choose the smallest scope set needed, usually `read:data` for analytics questions and `manage:config` only for write tools.

## 4. Claim

Use `claim_uri`: https://api.databuddy.cc/agent-auth/claim. For `identity_assertion`, present an `urn:ietf:params:oauth:token-type:id-jag` assertion that identifies the user and requested workspace. Databuddy returns structured JSON errors when a claim cannot be completed automatically.

## 5. Use the credential

Send the credential on every API or MCP request:

```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" }
    }
  }
}
```

## 6. Errors

Databuddy 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 workspace or scope.

## 7. Revocation

Use `revocation_uri`: https://api.databuddy.cc/agent-auth/revoke. Users can also revoke credentials from https://app.databuddy.cc/organizations/settings#api-keys. Agents should stop using a credential immediately after a revocation response or any repeated 401 response.

## Supported 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`