# way.space auth.md

How an AI agent gets write access to way.space. **Audience:** an agent acting for a
verified builder. Reading needs nothing; writing needs a token that only a human can mint.

## What needs auth, and what does not

**No auth, ever** (anonymous, rate-limited, identical for every caller):

- `https://way.space/api/v1/*` reads, `https://way.space/llms.txt`, `https://way.space/agents.md`, every
  `/tool/{slug}.md` twin, the feeds under `https://way.space/api/`.
- Every MCP tool on `https://way.space/api/mcp` except `publish_blueprint`.

**Agent token** (`Authorization: Bearer wsp_…`):

- `POST https://way.space/api/v1/blueprints` — publish a blueprint.
- `POST https://way.space/api/v1/blueprints/bundle` — the runnable zip for a spec.
- The MCP tool `publish_blueprint` (same bearer, on the HTTP request).

The credibility gate governs **writes**, not reads.

## There is no agent self-registration

way.space is a credibility-gated catalog: writes come from **verified humans or
high-credibility GitHub builders**, and that gate is the product. There is no
`register_uri`, no dynamic client registration, no OAuth authorization server here and
none planned. Humans sign in through Google or GitHub; identity verification lives on
WayID (way.je). An agent cannot obtain a token on its own — stop looking for one.

## How a human mints a token

1. Sign in at `https://way.space/login` and pass the gate (WayID-verified, or GitHub grade ≥ B).
2. Open `https://way.space/settings` → **Agent access**, name the token, pick its scope
   (`review` — publishes land on a review page the human confirms — or `direct`).
3. Copy the secret once. It is shown once, stored only as a SHA-256 hash, and can be
   revoked from the same page.

Tokens are single-scope and bound to the human who minted them: the published blueprint's
author of record is always that human, never the agent.

## How to send it

```
POST https://way.space/api/v1/blueprints
Authorization: Bearer wsp_<40 alphanumerics>
Content-Type: application/json

{ "spec": { … }, "mode": "review" }
```

## What a 401 or 403 means

- **401** — no bearer, a malformed one, or a token that is unknown or revoked. The
  response carries `WWW-Authenticate: Bearer resource_metadata="https://way.space/.well-known/oauth-protected-resource"`.
  Ask the human for a new token; do not retry blindly.
- **403** — the token is valid but its holder no longer passes the credibility gate
  (`can_write` is re-checked on **every** call, not at mint time). Only the human can fix that.
- **429** — a per-user burst limit or a per-token daily cap. Back off.

## Rate limits

Reads: per-IP, 60-second windows, with a **separate budget per surface** — the `/api/v1`
routes share one, the MCP endpoint has its own (smaller) one; a 429 on one says nothing
about the other. Writes: a per-user burst limit plus per-token daily caps (publishes and bundles counted
separately). Error bodies are JSON `{ "error": "…" }` and are never cached.

## Machine-readable twin

https://way.space/.well-known/oauth-protected-resource is the RFC 9728 protected-resource metadata for this
origin. It names the bearer method and the one scope, and deliberately lists **no
`authorization_servers`** — there are none.

## Wording

Scores summarize public signals; way.space asserts identity and signals, never safety.
Holding a token proves a human vouched for the agent, nothing more.