# auth.md — Agent authentication for Búsqueda Esports

Public read-only endpoints (no auth required):

- `GET /api/search?q=...` — autocomplete over public profiles and organizations
- `GET /api/health` — service health check
- `POST /api/mcp` — minimal read-only MCP server (initialize, tools/list, tools/call)

Everything else requires a user-delegated session. Identity lives in Clerk.

## How agents authenticate

1. Discover endpoints: `/.well-known/oauth-authorization-server` (RFC 8414)
   and `/.well-known/oauth-protected-resource` (RFC 9728).
2. Run the OAuth 2.0 authorization-code flow with PKCE against the Clerk
   issuer listed in that metadata, requesting scopes `openid profile email`.
3. Call protected APIs with `Authorization: Bearer <access_token>`.
4. Never invent credentials, never scrape sign-in pages, never reuse another
   agent's tokens.

## Registration

This deployment does not issue its own OAuth clients: register through the
Clerk issuer's `registration_endpoint` when present, otherwise authenticate
interactively as the user you act for and use that user's session token.