# auth.md

How an AI agent registers with and authenticates to Stacktree.

Stacktree is an MCP-native publish primitive: an agent publishes HTML and
gets back a private, unguessable URL. There are eight ways to authenticate,
from zero-setup to full OAuth — including paying as the credential, the page's
own claim token, and, for wallet-paid pages, the wallet itself.

**Connecting over MCP needs no browser.** The hosted MCP endpoint
(`https://api.stacktr.ee/mcp`, streamable HTTP) accepts EITHER an OAuth 2.1 access
token (method 1) or a plain `Authorization: Bearer stk_live_...` API key
(method 2) — the same key that works on every REST route. Send one or the
other, never both. Session cookies are refused there on purpose. If you have no
key: buy one with no human at all (method 4), or get one from a human who is
nearby but whose browser you cannot drive (method 8).

## Audience

AI agents and MCP clients (Claude Code, Cursor, Codex, Claude.ai) and any
server-side or CLI tool that publishes to Stacktree's REST API.

Official CLI: `npx stacktree-install` — published on the npm registry as
[stacktree-install](https://www.npmjs.com/package/stacktree-install); it signs
you in via the browser and configures the MCP server for the agents you pick.
The MCP stdio server itself is
[stacktree-mcp](https://www.npmjs.com/package/stacktree-mcp) on npm.

## Machine-readable metadata

- OAuth authorization server: `https://api.stacktr.ee/.well-known/oauth-authorization-server` (includes an `agent_auth` block)
- OAuth protected resource, MCP server: `https://api.stacktr.ee/.well-known/oauth-protected-resource/mcp` (resource `https://api.stacktr.ee/mcp`)
- OAuth protected resource, REST API: `https://api.stacktr.ee/.well-known/oauth-protected-resource` (resource `https://api.stacktr.ee`)
- OpenAPI: `https://stacktr.ee/openapi.json`

## Registration methods

### 1. OAuth 2.1 with Dynamic Client Registration (recommended for connectors)

For MCP connectors and any agent acting on behalf of a signed-in user.

- Register a client: `POST https://api.stacktr.ee/oauth/register` (RFC 7591)
- Authorize: `https://api.stacktr.ee/oauth/authorize` (authorization code + PKCE, S256)
- Exchange code for token: `POST https://api.stacktr.ee/oauth/token`
- Revoke: `POST https://api.stacktr.ee/oauth/revoke` (RFC 7009)
- Scopes: `sites:write`, `sites:read`
- Send the access token as `Authorization: Bearer <token>`

Most clients discover all of this automatically from
`https://api.stacktr.ee/.well-known/oauth-authorization-server`.

### 2. API key (recommended for server-side and CLI agents)

- Create a key in the dashboard: `https://app.stacktr.ee/api-keys`
- No human at the keyboard? Get a key without one: buy it (method 4) or run the
  device-code flow (method 8).
- Send it as `Authorization: Bearer stk_live_...`
- Works on every REST route and on `POST https://api.stacktr.ee/mcp` (MCP over
  streamable HTTP). One credential, both surfaces.
- Keys are long-lived; revoke them from the same dashboard page.
- The key inherits the account's plan. On the free plan that is 3 pages in total
  (deleting one does not free the slot), every page expiring after 7 days, and no
  passcodes or email gates. Publishing past a limit returns `402` with a
  `plan_*` error code; `GET /me` returns the caller's own `limits` object, which
  is the right thing to read instead of hard-coding a number.

### 3. Anonymous (no registration)

For ephemeral, one-off publishes that need no account.

- `POST https://api.stacktr.ee/sites` with a `multipart/form-data` body and no
  Authorization header.
- You get back a private, unguessable URL that lives for 24 hours.
- Example: `curl -X POST https://api.stacktr.ee/sites -F file=@index.html`
- The response carries a `claim_token`. Keep it: it adopts the page into an
  account later, and until then it is the page's own update credential
  (method 7), so an agent with nothing but `curl` can keep one URL current.

### 4. Pay-to-provision (no human in the loop)

For an agent that wants a persistent identity without a human creating an
account. The agent pays, and the payment is the credential. Payment replaces
the human sign-up step as the anti-abuse gate.

- `GET https://api.stacktr.ee/provision` returns the rail menu: which agentic-commerce
  protocols are accepted and which are currently live.
- `POST https://api.stacktr.ee/provision` carries the payment. Dispatch is by mechanism:
  - **x402** (USDC): send a base64 `PAYMENT-SIGNATURE` header. A bare POST
    returns `402` with a `PAYMENT-REQUIRED` header describing the terms.
  - **MPP** (Machine Payments Protocol): send `Authorization: Payment
    <credential>`; the Stripe method carries a shared payment token.
  - **ACP** (Agentic Commerce Protocol): `POST { "acp_shared_payment_token":
    "spt_..." }` — Stacktree redeems it as an ACP-compatible seller.
  - **AP2** (the payment layer behind UCP and Google surfaces): `POST {
    "ap2_mandate": {...} }`.
- On success you receive an `stk_live_...` API key, shown once. Use it as in
  method 2. Price is flat and shown in the rail menu.
- The provisioned identity sits on the free plan, so the limits in method 2
  apply. `GET https://api.stacktr.ee/unlock` lists what buys past them (make_permanent,
  custom_domain, higher_limits) with live prices.
- Publishing one permanent page and nothing else? Skip provisioning: pay per
  publish at `https://agents.stacktr.ee/api/publish`. That page sits outside the
  plan ladder, so it does not expire. See `https://stacktr.ee/x402.md`.
- Revising that page later needs no key either — the wallet that paid is the
  page's update credential (method 6).

### 5. Pay link (hand the payment to a nearby human)

For an agent with no wallet whose human is right there at the terminal.
The payment twin of the device-code flow:

- `POST https://api.stacktr.ee/pay/sessions` with `{ "feature": "provision" }` (no
  auth), or `{ "feature": "custom_domain" }` etc. with your API key.
- The response includes a short URL and a ready-to-print terminal QR
  (`qr` field). Print it; the human scans and pays by card on their phone
  (Stripe Checkout, about two taps).
- Poll `GET https://api.stacktr.ee/pay/sessions/{code}/poll` every few seconds. On
  `provision` the poll returns the new API key once; on unlocks it confirms
  the entitlement is active. Continue your task immediately.
- **Scan once, draw silently:** pass `"amount_minor"` above the price (up to
  2000 = $20) on `provision`, or use `{ "feature": "topup", "amount_minor":
  1000 }` later, and the surplus becomes a prepaid balance on the identity.
  Future paid actions draw from it automatically — no 402, no scan — until it
  runs out. Unlock 402 responses show the current balance.

### 6. Wallet signature (update the pages your wallet paid for — no key)

The wallet that paid for a page over x402 IS that page's update credential.
No account, no API key, nothing to store beyond the wallet you already hold:

- `POST https://api.stacktr.ee/wallet-auth/challenge` with `{ "wallet": "0x…" }` —
  returns `{ challenge, message, expires_at }`.
- `personal_sign` (EIP-191) the `message` with that wallet.
- Retry your request with `Authorization: Wallet challenge=WAUTH-…,sig=0x…`
  on `PUT https://api.stacktr.ee/sites/{id}`, sending `{"html": "…"}` as
  `application/json` (or the multipart `file` field, like any replace).
  The URL stays the same; revisions are free.
- Challenges are **single-use** with a 5-minute TTL — request a fresh one per
  update. Scope is exactly the pages carrying that `payer_wallet`; a page
  adopted into an account stays updatable while the wallet remains linked
  (`https://app.stacktr.ee/wallets`). EVM EOA wallets only for now (no
  EIP-1271, no Solana). A Solana payer signs nothing: its page's
  `claim_token` is the keyless update credential (method 7), same URL, also
  free.
- A wallet-paid publish response also carries `next.receipt_url`: a stable
  page listing every page that wallet has paid for, the request that revises
  each one, and a button to move them into an account. The link is the
  credential and the payer address is never accepted in its place, which is why
  the challenge endpoint above does not return it: that endpoint gates only on
  "this wallet is known here", and payer addresses are public on chain.

### 7. Claim token (update an unclaimed page, no account, no wallet)

The plainest path, and the only keyless one that works on every rail. An
anonymous publish (free, or a paid x402 one-off on any chain) returns a
`claim_token`. While the page is unclaimed, that token IS the page's update
credential:

```bash
curl -X PUT https://api.stacktr.ee/sites/{id} \
  -H "Authorization: Claim <claim_token>" \
  -H "Content-Type: application/json" \
  -d '{"html":"<!doctype html>…"}'
```

(`-F file=@new.html` instead of the last two lines does the same thing, and
is the only shape that carries a zip, a PDF, or e2e ciphertext.)

- Same URL, same page id: replacing never mints a second URL. Repeatable, no
  challenge, no signature, nothing to install.
- Scope is one verb on one page: replace its content. Not claiming, not
  deleting, not settings, not any other page. Send it *instead of* a Bearer or
  Wallet header, never alongside one.
- It stops working the instant the page is claimed: a claim rotates the token
  into the account, and from then on only that account's API key or OAuth token
  can update the page. It is also refused on an expired page (a free anonymous
  page still dies at 24 hours, and an unclaimed page cannot be restored) and
  for an actor on the abuse blocklist.
- Anonymous updates are rate limited per IP (standard `RateLimit` headers on
  the response) and need a direct client connection, like anonymous publishing.
- **Treat it as sensitive as the page.** Anyone holding it can replace the
  content behind a link you already sent a client. Store it with the page id;
  do not paste it into logs or a shared transcript.

### 8. Device code (a human's account, without a browser)

RFC 8628, the same grant a TV app uses. For an agent that has a human it can
show a line of text to, but no browser of its own, and that should publish into
that human's existing account rather than a new one. This is the flow
`npx stacktree-install` runs.

```bash
# 1. start it — no auth
curl -sX POST https://api.stacktr.ee/api-keys/device-code \
  -H 'content-type: application/json' -d '{"client_hint":"my-agent"}'
# → { device_code, user_code, verification_url, verification_url_complete, interval, expires_in }

# 2. print verification_url_complete for the human, then poll every "interval" seconds
curl -sX POST https://api.stacktr.ee/api-keys/device-code/poll \
  -H 'content-type: application/json' -d '{"device_code":"…"}'
# → {"status":"pending"}                        keep polling
# → {"status":"authorized","api_key":"stk_live_…"}   store it, it is shown once
# → {"status":"denied"} | {"status":"expired"}  stop
```

- The human approves at `https://app.stacktr.ee/connect/cli`, where they see
  the `user_code` and the `client_hint` you sent, on whatever device they
  already have signed in.
- The key belongs to THEIR account and inherits THEIR plan, which is the whole
  point: the pages you publish land where they can find them.
- Codes expire after 10 minutes and the key is released on exactly one poll —
  if you lose it, start again.
- Neither call is authenticated; both are rate limited per IP.
- Use it instead of method 4 when the account should be a person's. Use method 4
  when there is no person to ask.

## Notes

- Anonymous and API-key publishing use the same REST endpoint; the
  difference is whether an Authorization header is present.
- There is no separate signup step for agents: registration and first use
  are the same call. Sign in via the dashboard to claim anonymously-published
  sites into an account; a claim counts as a publish, and the page gets the
  longest life the claiming account's plan allows.
