# BotVisibility Authentication

> How agents authenticate with the BotVisibility API. The public API is open —
> auth is only needed to raise rate limits.

## TL;DR

- **No auth required** for the free tier. Just call
  `GET https://botvisibility.com/api/scan?url=<site>&format=json`.
- To **raise your daily allowance**, obtain an anonymous OAuth 2.0
  client-credentials token (`scan:read` scope) and send it as a bearer token, or
  send an `X-API-Key` header.

## Discovery (RFC 8414 + RFC 9728)

| Metadata | URL |
| --- | --- |
| Authorization Server | `https://botvisibility.com/.well-known/oauth-authorization-server` |
| Protected Resource | `https://botvisibility.com/.well-known/oauth-protected-resource` |
| Token endpoint | `https://botvisibility.com/api/agent/token` |

- **grant_types_supported:** `client_credentials`
- **scopes_supported:** `scan:read`
- **bearer_methods_supported:** `header`

## Pick a method

| You want… | Use |
| --- | --- |
| The free tier, no setup | No auth — just call the endpoint. |
| A higher daily allowance, self-serve | OAuth 2.0 client-credentials token (`scan:read`). |
| A fixed higher limit for a known integration | An `X-API-Key` (request one via https://botvisibility.com/contact). |

## Register / claim credentials

No registration is required for the OAuth `client_credentials` flow — it is
**anonymous**: any client may request a `scan:read` token directly from the
token endpoint, no client_id/secret provisioning step. This is by design so
agents can self-onboard with zero human interaction. API keys, for named
higher-limit integrations, are issued on request via
https://botvisibility.com/contact.

## Flow: OAuth 2.0 client credentials

```
# 1. Request a token
curl -X POST https://botvisibility.com/api/agent/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"client_credentials","scope":"scan:read"}'
# -> { "access_token": "...", "token_type": "Bearer", "scope": "scan:read" }

# 2. Call the API with the bearer token
curl -H "Authorization: Bearer <access_token>" \
  "https://botvisibility.com/api/scan?url=example.com&format=json"
```

## Alternative: API key

Send an `X-API-Key: <key>` header on any request for a higher rate limit.

## Rate limits

Responses carry both legacy `X-RateLimit-*` and IETF `RateLimit-*` headers
(`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, `RateLimit-Policy`).
Over the free allowance the API returns **HTTP 402** with x402 payment
requirements — see https://botvisibility.com/pricing.md

## Revocation / rotation

Tokens are short-lived bearer tokens. To rotate, simply request a new one from
the token endpoint — there is no long-lived secret to leak. Because the flow is
anonymous and scoped to `scan:read` (read-only), a leaked token grants nothing
beyond scanning at the raised allowance and expires on its own. To revoke an
`X-API-Key`, contact us at https://botvisibility.com/contact.

## Errors

All error responses are JSON with a typed envelope: `{ "error", "code",
"message", "docs" }`. See https://botvisibility.com/openapi.json