> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quote.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys and scoped OAuth 2.1

REST registration issues a `qd_test_` key. Send `Authorization: Bearer <token>` on private requests. Public packs and provider discovery do not need credentials. Never put a bearer key in a URL, browser bundle or log.

The owner may claim an agent using a verified matching human session. Poll `/v1/auth/agent-status` with the poll token or test key; a live key may be returned once. This sensitive claim route is REST/direct-key access only, never delegated OAuth; OAuth MCP status requires `quote_id`. Claiming does not configure payment processing. Revocation at `POST /v1/auth/revoke` invalidates agent credentials.

OAuth discovery starts at `https://mcp.quote.dev/.well-known/oauth-protected-resource`. Its `authorization_servers` entry identifies the API issuer. Read that issuer's `/.well-known/oauth-authorization-server` rather than guessing endpoint URLs. Register a public client with `POST /oauth/register`, an exact redirect URI and `token_endpoint_auth_method: none`.

Use authorization code flow with PKCE S256, a fresh verifier and state of at least 16 characters. Exchange the one-time code at `/oauth/token` with the verifier and identical redirect URI. Include `resource=https://mcp.quote.dev/mcp` in authorization and token requests (local API: `http://localhost:8788/mcp`). No refresh tokens are issued. Request only advertised scopes (for sandbox: `estimates:write`, `quotes:dry_run`). OAuth grants do not upgrade sandbox access or provide live-payment authorization. Authorization requires a verified owner session, a claimed matching owned agent ID and explicit approval of `agent_id` and `mode`; never send an owner's password to an agent.

A 401 includes `WWW-Authenticate: Bearer resource_metadata="https://mcp.quote.dev/.well-known/oauth-protected-resource"`. Rediscover or obtain a valid token; do not loop retries. On 429 honor `Retry-After`.

[Machine-readable onboarding](https://quote.dev/auth.md) stays under 2,000 approximate tokens. See [MCP and OAuth](https://docs.quote.dev/mcp-and-oauth.md).

Sandbox agent scopes default to `estimates:write quotes:dry_run`; pack and status reads are inferred. Live `quotes:write` must be operator-provisioned: claiming or authorizing an agent cannot self-promote its scopes. Delegated tokens preserve mode with `qd_test_oauth_` or `qd_live_oauth_` prefixes.

The implementation uses narrow custom OAuth routes and D1 grants backed by Better Auth human sessions, not the Better Auth MCP plugin. The installed plugin provides generic OIDC behavior but does not model agent ownership and mode-bound D1 grants. Browser approval stays at the API issuer so its human session cookie remains API-origin.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.