# Auth.md — CheapCrawler API Authentication & Checkout Verification

## Public Agent Endpoints (No OAuth Required)

- **`GET /api/agent/buy`**: Publicly accessible with no OAuth token or API key required. Returns volume pricing tiers, live USD quotes for 1–999 licenses (`subscription` or `one_time`), and a pre-filled `/buy` checkout link.
- **`GET /api/health`**: Public health check endpoint returning `{ "status": "ok", "service": "cheapcrawler-edge-worker" }`.

## Checkout Verification Flow (Human-in-the-Loop)

To ensure license keys and tax invoices are delivered only to an inbox the buyer controls, checkout on `https://cheapcrawler.com/buy/` uses a single verified flow:

1. **Ask for Email & Billing Mode**: If the buyer has not yet shared their email address or preferred billing mode (`subscription` vs `one_time`), ask for both first so the checkout URL can pre-fill all fields.
2. **Pre-filled Checkout Link**: Fetch a live quote from `GET /api/agent/buy?quantity=5&billing_mode=subscription&email=buyer@company.com` and present the returned `checkout_url` (`/buy?qty=5&mode=subscription&email=buyer@company.com`) to the user.
3. **1-Click 6-Digit Email OTP**: On `/buy`, quantity, billing mode, and email are already pre-filled. The buyer clicks **Send code** and enters the 6-digit one-time code sent to their inbox.
4. **Paddle Checkout**: Once verified, the inline Paddle payment form unlocks so the buyer can review tax, local currency, and authorize payment directly on Paddle.

## Payment & Merchant of Record

- All payments, local currency conversions, VAT/GST/sales tax calculations, and tax invoices are processed 100% by **Paddle** as Merchant of Record.
- Agents never handle raw payment card details; the human buyer completes payment directly in Paddle Checkout.
