# auth.md — agent registration and authentication

Site: https://knowngood.sh — a probe-verified index of agent-ready websites.
Updated: 2026-08-27

## Agent audience

AI agents and automated clients using our search API (`/api/find`) and MCP
server (`/mcp`). Reading is open to everyone — no account, no credential.
Registration exists for one purpose: a higher rate limit.

## Discover

- Protected resource metadata: `/.well-known/oauth-protected-resource`
- Authorization server metadata (carries the `agent_auth` block):
  `/.well-known/oauth-authorization-server`

## Registration

Supported registration method: **anonymous** (instant, self-serve).
Credential type: **api_key**.

    POST https://knowngood.sh/agent/auth
    Content-Type: application/json

    {"type": "anonymous", "requested_credential_type": "api_key"}

Response (200):

    {
      "registration_type": "anonymous",
      "credential_type": "api_key",
      "credential": "kg_...",
      "credential_expires": null,
      "scopes": ["search"],
      "daily_limit": 10000,
      "claim_url": "https://knowngood.sh/agent/auth/claim",
      "claim_token": "clm_..."
    }

Store the credential; it is shown once. Registrations are capped at 3 per
caller per day. Fallback registration method: email hello@knowngood.sh
(human-approved, same credential type — and the route to higher limits).

## Credential use

Send the credential as a bearer token in the Authorization header
(preferred), on `/api/find` and `/mcp`:

    Authorization: Bearer kg_...

or as a query parameter: `?key=kg_...`

## Claim ceremony

Manual for now: email hello@knowngood.sh from your operator address,
quoting your `claim_token`, to attach an operator identity to an anonymous
registration or to arrange limits above the default.

## Rate limits

- Without a credential: 500 requests per UTC day per caller.
- With a registered credential: 10,000 requests per UTC day.
- Past the limit: HTTP 429 with a `retry-after` header; counters reset at
  midnight UTC. A pay-per-request tier (x402) is planned.

## What a credential never does

A credential never changes what you see. Placement in this index cannot be
bought, requested, or influenced by any credential — capabilities are
verified by probe, and every listing carries the date it was tested.

## Endpoints

- Register: `POST /agent/auth`
- Claim: `/agent/auth/claim`
- Search API: `GET /api/find?q=...`
- MCP server (streamable HTTP): `POST /mcp`
- API catalog: `/.well-known/api-catalog`
- MCP server card: `/.well-known/mcp/server-card.json`
- Agent overview: `/llms.txt`
- Suggest a site for probing: `/submit`