# auth.md — BuzzonChat

Agent-facing authentication and registration instructions for the BuzzonChat
public API.

BuzzonChat does **not** operate an OAuth authorization server. There is no
`/.well-known/oauth-authorization-server`, no `/.well-known/openid-configuration`,
and no `/.well-known/oauth-protected-resource` for this API — do not attempt an
OAuth or OIDC token exchange against this domain. The API uses **static API keys**.

## Audience

Autonomous agents and programmatic clients that want to scan websites for
AI-readiness on behalf of a BuzzonChat account holder.

## Registration / provisioning

There is **no programmatic (agent-initiated) registration endpoint**. A human
must provision the credential:

1. Sign in at <https://buzzonchat.com/login>. Sign-in is **Google OAuth only** —
   there is no email/password registration. An account is created on first
   Google sign-in.
2. Programmatic API access requires the `api-access` feature, which is enabled by
   default on the **Agency** plan. See <https://buzzonchat.com/pricing>.
3. With that plan active, generate a key at
   <https://buzzonchat.com/dashboard/api-keys>.

## Credential usage

Send the key in the `X-API-Key` header on every request:

```
GET https://api.buzzonchat.com/api/v1/sites
X-API-Key: <your-api-key>
```

Keys are bearer credentials scoped to a single account — treat them as secrets
and never embed them in client-side code.

## Revocation

Keys can be revoked at any time from <https://buzzonchat.com/dashboard/api-keys>.
Revocation takes effect immediately. Per-key usage is logged for quota and
billing visibility. There is no programmatic revocation endpoint.

## API surface

- OpenAPI description: <https://api.buzzonchat.com/api/v1/openapi.json>
- API catalog (RFC 9727): <https://buzzonchat.com/.well-known/api-catalog>
- Agent skill: <https://buzzonchat.com/.well-known/agent-skills/buzzonchat-api/SKILL.md>
- Human documentation: <https://buzzonchat.com/api-reference>
- Health / status (no auth): <https://api.buzzonchat.com/api/health>

All endpoints are under `https://api.buzzonchat.com`:

| Method | Path | Purpose |
| --- | --- | --- |
| POST | `/api/v1/scan` | Enqueue an AI-readiness deep scan for a URL |
| GET | `/api/v1/scans/{scanId}` | Fetch scan result |
| GET | `/api/v1/sites` | List your scanned sites |
| POST | `/api/v1/webhooks` | Subscribe a webhook (scan.completed, score.dropped, kit.purchased) |
| DELETE | `/api/v1/webhooks/{id}` | Unsubscribe a webhook |

Every response uses the envelope `{ "success": boolean, "data": T | null, "error": string | null }`.

## Support

Email <support@buzzonchat.com>.