# ClearList Authentication (for AI agents)

ClearList uses a passwordless, agent-friendly model: an emailed one-time code is
exchanged for a long-lived API key. No OAuth redirect, no password.

## Flow
1. **Send code** — `POST /api/auth/send-code` with `{ "email": "seller@example.com" }`. Emails a 6-digit code.
2. **Verify + get key** — ask the user for the code, then `POST /api/auth/verify-code` with `{ "email": "seller@example.com", "code": "482019", "agent": true }`. Returns `{ "apiKey": "cl_<64-hex>" }` and creates the account if new.
3. **Authenticate requests** — send the key on every call: header `X-ClearList-API-Key: cl_<64-hex>`.

## Key facts
- Header: `X-ClearList-API-Key`
- Key format: `cl_` followed by 64 hex characters
- Keys are SHA-256 hashed at rest; the raw key is returned once.
- Expiry is tied to tier (free / Move Sale = 30 days, Garage Sale = 60 days). Expired keys return HTTP 401.
- A 401 response includes a `WWW-Authenticate: Bearer` header pointing at the protected-resource metadata.
- The web UI / PWA alternatively authenticates with `Authorization: Bearer <firebase_id_token>`.

## Discovery documents
- OAuth Protected Resource: https://clearlist.me/.well-known/oauth-protected-resource
- OAuth Authorization Server: https://clearlist.me/.well-known/oauth-authorization-server
- MCP server card: https://clearlist.me/.well-known/mcp/server-card.json
- OpenAPI 3.1 spec: https://clearlist.me/.well-known/openapi.json

Full docs: https://clearlist.me/developers#clearlist-authentication