# AI Score auth.md

> Agent authentication guide for the AI Score scan API
> (https://aiscore.getbags.app/api/scan).

## Who this is for

AI agents that want to scan a site for agent-readiness. The free tier needs
**no API keys, OAuth, signup, or registration**.

## Free tier (no credentials)

`POST /api/scan`

```json
{
  "url": "https://www.getbags.app",
  "format": "json",
  "fresh": false
}
```

- `format`: `"json"` (default) or `"agent"` (markdown summary)
- `fresh`: `true` to bypass the 1-hour scan cache
- Free rate limit: **10 requests / minute** per client IP (`429` when exceeded;
  see `X-RateLimit-*` headers)
- On `429` without payment, the body includes `code: "RATE_LIMITED"` and an
  `upgrade` hint pointing at the x402 paid path below

`GET /api/health` — liveness probe (always free).

## Paid access (x402 micropayment)

When the free IP rate limit is exceeded, `POST /api/scan` and `POST /mcp`
require a **$0.01 USDC** payment on **Base** (Coinbase CDP facilitator):

1. Retry the same request without a payment header → HTTP `402` with a
   `PAYMENT-REQUIRED` challenge (x402 v1 `accepts` + JSON body).
2. Sign and attach a `PAYMENT-SIGNATURE` header (or legacy `X-PAYMENT`) and
   retry. On success the response includes `PAYMENT-RESPONSE` settlement
   proof and the scan proceeds outside the free-tier limiter.
3. There is **no account or API key** for the paid tier — payment replaces
   registration.

Ops / internal dogfood may skip the limiter with
`X-Aiscore-Paid: <AISCORE_PAID_BYPASS_SECRET>` (not for public agents).

## MCP

`POST /mcp` — MCP Streamable HTTP. Tool: `scan_site` with
`{ "url": string }`. Same free-tier rate limit and x402 paid path as
`/api/scan`. No bearer tokens.

## Registration

**None.** AI Score does not issue API keys or run an OAuth authorization
server. Agents either call the free tier anonymously or pay per request via
x402 when rate-limited.

## Discovery documents

Plain URLs (no code formatting) so scanners that extract links resolve them
verbatim:

- OAuth protected resource (RFC 9728): https://aiscore.getbags.app/.well-known/oauth-protected-resource
  — declares the scan API public (`authorization_servers: []`,
  `bearer_methods_supported: []`) and points here
- API catalog (RFC 9727): https://aiscore.getbags.app/.well-known/api-catalog

AI Score does **not** publish `/.well-known/openid-configuration` or
`/.well-known/oauth-authorization-server` — there is no authorization
server to describe.

## Support

- Catalog: https://aiscore.getbags.app/llms.txt
- Full agent surface: https://aiscore.getbags.app/llms-full.txt
- BAGS (charge agents on your own APIs): https://www.getbags.app