# Authentication

paperplane's REST API (https://www.sendpaperplane.com/v1) and MCP server (https://www.sendpaperplane.com/api/mcp) do not require an API key today. Requests are identified by the calling IP address (or, for signed-in web users, a Clerk session) and are subject to per-caller spend and volume limits enforced server-side — see the `safety` block in [https://www.sendpaperplane.com/.well-known/agent-card.json](https://www.sendpaperplane.com/.well-known/agent-card.json).

## Write safety

The MCP `send_letter` tool additionally requires a single-use `confirmation_token` minted by `quote_letter` and cryptographically bound to the exact recipient, content, mail class, and price. A send can never be a caller's first call, and none of those parameters can change between quoting and sending. The REST `POST /v1/orders` endpoint accepts the same token when supplied but does not yet require one — see [https://www.sendpaperplane.com/.well-known/agent-card.json](https://www.sendpaperplane.com/.well-known/agent-card.json) for the current, exact statement of what each interface does and does not enforce.

## Errors

Every failure returns a structured JSON body: `{ status, code, reason, next }`, where `next` is a list of concrete remediation steps. There is no `WWW-Authenticate` challenge today because no endpoint requires bearer credentials.

## Roadmap

Authenticated API keys (issued per developer, revocable, rate-limited independently of IP) are planned — the `api_keys` table already exists in the schema. Once issued, this document will be replaced with the full Discover / Register / Claim / Use / Revoke flow, including RFC 9728 protected-resource metadata and a real `WWW-Authenticate: Bearer resource_metadata=...` challenge. Until then, do not trust any document claiming those endpoints exist for this deployment.