# Authentication — AI Agent City

There is **no unauthenticated read path**, on REST or on MCP. Every read of an
agent's own data requires proof of access.

## Credentials

| Credential | Header | Scope |
|---|---|---|
| `agent_secret` | `X-Agent-Secret` | one agent |
| `workspace_key` | `X-Workspace-Key` | every agent in a workspace |

These four agent-write routes also require the header
`AL-API-Version: 2026-09-01`:

- `POST /v1/track`
- `POST /v1/budget`
- `POST /v1/approvals`
- `POST /v1/approvals/{id}/decide`

A missing or stale value is rejected `400 version_header` — this is the header
that bites first, because the first call below fails without it. It is NOT a
blanket rule for `/v1/*`: `/v1/check`, `/v1/webhooks` and `/v1/billing/*` are not
gated, and `/mcp/` is not gated either.

A **write** to a new `agent_id` claims it: send a `workspace_key` in the body of
the first `POST /v1/track` or `POST /v1/budget`. The response mints an
`agent_secret` **once** — save it. Every later write to that same `agent_id` must
carry that `agent_secret`, and the `workspace_key` is never needed again for it.
A missing or invalid key on a new claim returns `401 workspace_key_required`.

## Getting a workspace — three ways, none needing a human to approve it

1. **An agent buys one itself.** `POST /v1/billing/x402` with an `X-PAYMENT`
   header carrying a signed x402 `exact` payment. It settles on Base MAINNET (eip155:8453) in real USDC. The paying wallet pays real money; the workspace is live immediately.
   The response returns `workspace_id` + `workspace_key` (shown once), bound to
   the paying wallet. No card, no email, no human. Terms and the live price:
   `/.well-known/x402`.
2. **A free workspace.** `POST /start` — no signup, no login, no card, capped at
   3 agents. A 4th new `agent_id` returns `402` with the upgrade paths in the
   error body. `GET /start` renders the form only; it does not mint.
3. **A human subscribes.** `POST /v1/billing/checkout` with `X-Workspace-Id` and
   `X-Workspace-Key` returns a Stripe link a human opens to pay. (`/start?plan=starter`
   is the human door and does **not** subscribe.) Prices: `/pricing.md`.

## Authoritative sources

- Full buyer walkthrough: `/skill.md`
- Every endpoint, with schemas: `/openapi.json`
- Rail terms and the live price: `/.well-known/x402`
- Agent-readable index of all surfaces: `/okf/index.md`
- Machine-readable price sheet: `/pricing.md`