# Immersive Commons API Authentication (auth.md)

Immersive Commons issues per-user agent tokens. An agent registers its
human once, receives a bearer token, then calls the MCP server, the A2A
endpoint, and the REST surface with it. Ten SIGNAL, presentations, news,
and donation tools are public and need no token.

## Discover

Machine-readable auth metadata (this file is the prose mirror):

- Authorization-server metadata (RFC 8414): https://www.immersivecommons.com/.well-known/oauth-authorization-server
  — carries the `agent_auth` extension block: `register_uri`, `claim_uri`,
  `verification_uri`, `revocation_uri`, `key_register_uri`, and
  `identity_types_supported`.
- Protected-resource metadata (RFC 9728): https://www.immersivecommons.com/.well-known/oauth-protected-resource
- Full manifest (scope catalog, endpoints, rate limits): https://www.immersivecommons.com/.well-known/ai-agent.json
- A2A agent card: https://www.immersivecommons.com/.well-known/agent-card.json

Note: API 401s do not yet carry a `WWW-Authenticate: Bearer
resource_metadata="..."` hint — start from this file or the well-known
documents above rather than probing for the header.

## Pick a method

`identity_types_supported` is `["anonymous"]`: the agent holds no prior
identity of its own; a signed-in human authorizes it. Identity chaining
via `identity_assertion` (e.g. `id-jag` /
`urn:ietf:params:oauth:token-type:id-jag`) is NOT offered. The credential
issued is an api_key-style bearer token.

Three registration paths. **Only the first can be completed by an agent with
no human present** — start there if you are reading this unattended.

0. **Sandbox mint (anonymous, no human, no signup).** One POST returns a
   working bearer token immediately:

   ```
   curl -X POST https://www.immersivecommons.com/api/agent/sandbox/mint \
        -H 'Content-Type: application/json' -d '{}'
   ```

   Returns `{ ok, token, token_type, sandbox: true, scopes, expires_in }`.
   Deliberately narrow, and these limits are the whole design — it exists so
   an agent can prove the surface works before asking a human for anything:
   - exactly one scope, `events:read_upcoming` — it is not requestable,
   - 24h TTL, `sandbox: true`,
   - rate-limited per IP, tighter than the device-code flow.

   For anything beyond that one scope, come back with path 1. Note also that
   a large part of this surface needs **no token at all** — see the
   public-tool list in https://www.immersivecommons.com/.well-known/ai-agent.json.

1. **Device-code flow (RFC 8628 — recommended for real use).** No human
   *credentials* ever reach the agent, but **a human must approve**: the
   agent shows a URL and waits. Steps in Register + Claim below.
2. **Browser mint (human-driven).** The human signs in at
   https://www.immersivecommons.com/floor10/agent-console, picks scopes, clicks Mint, and pastes
   the plaintext token into the agent's environment.

## Register

The `agent_auth.register_uri` is https://www.immersivecommons.com/api/agent/signup/start.

1. POST https://www.immersivecommons.com/api/agent/signup/start
   Body: `{ "scopes": ["read:public", "membership:read"], "client_name": "Your Agent" }`
   Returns: `{ device_code, user_code, verify_url, verify_url_complete, expires_in, interval }`.
   `scopes` is REQUIRED and non-empty; pick the narrowest set for your workflow.
2. **Print `human.display` verbatim, and nothing else from that response.**
   The reply carries a ready-made `human` block — one link, the code, how
   long it takes, and a heads-up that they will be asked to sign in (or make
   a free account). It is written to be read by a person in a terminal.

   **Do NOT print `device_code`.** It is a 43-character secret, the person
   never needs it, and dumping it is what makes a one-click approval look
   like a security incident. Dumping the whole JSON is the single most common
   way this step goes wrong: the human is handed eight cryptic fields and
   cannot tell which one to act on.

   While polling, stay quiet — do not narrate each attempt. Say one line when
   it succeeds.

   They approve at https://www.immersivecommons.com/signup-with-agent while signed in. Signed-out
   visitors are redirected to sign-in first and returned to the approval
   afterwards, so the link is always safe to hand over.

## Claim

The `agent_auth.claim_uri` is https://www.immersivecommons.com/api/agent/signup/poll.

3. Poll GET https://www.immersivecommons.com/api/agent/signup/poll?device_code=<device_code> every `interval` seconds.
   Returns `{ "status": "pending" }` until approval, then ONCE
   `{ "status": "completed", agent_token, tier, granted_scopes, next_steps }`.
   Store `agent_token` immediately — it is delivered exactly once;
   subsequent polls return 410.

Deviations from stock RFC 8628 (tolerate these in a generic client):

- The token endpoint is polled with GET plus a `device_code` query param.
- The success field is `agent_token`, not `access_token`.
- Pending is `200 { "status": "pending" }`, not `400 authorization_pending`.

## Use the credential

Bearer `agt_<base64url-32bytes>`, sent as `Authorization: Bearer agt_...`.
The server stores only a SHA-256 of the token; the plaintext is shown
once at mint time and is individually revocable.

Connect it to any of the three equivalent surfaces:

- MCP (Streamable HTTP): https://www.immersivecommons.com/api/mcp. Add the URL to your client, paste `agt_...` in the Authorization header.
- A2A (JSON-RPC 2.0): https://www.immersivecommons.com/api/a2a
- REST: per-endpoint docs in https://www.immersivecommons.com/llms.txt and https://www.immersivecommons.com/.well-known/ai-agent.json

Scopes are tier-gated; the full catalog (id, description, tier) lives in
https://www.immersivecommons.com/.well-known/ai-agent.json (auth.schemes[0].scopes). Starter sets:

- Read only: `read:public`, `membership:read`
- Events and RSVP: add `events:read_upcoming`, `events:rsvp`
- Submit a highlight: add `events:submit_recap`, `directory:search`

Scopes cannot be added to an existing token — call the `ic_capabilities`
MCP tool to learn what a NEW token needs, then re-register.

### Optional: signed requests (RFC 9421)

Upgrade a bearer token to bearer plus Ed25519 signature so a leaked bearer
alone is useless. Bind a public key (Clerk session required, so a leaked
bearer cannot bind its own key):

- Register: POST https://www.immersivecommons.com/api/agent/keys/register
- Revoke: POST https://www.immersivecommons.com/api/agent/keys/revoke
- Enforce toggle: POST https://www.immersivecommons.com/api/agent/keys/enforce-toggle

Covered components, freshness window, and header examples are in
https://www.immersivecommons.com/.well-known/ai-agent.json (signed_requests block). Skill:
https://www.immersivecommons.com/skills/ic-signed-agent/SKILL.md.

## Errors

- `400 { "error": "missing_scopes" }` — registration POST without a
  non-empty `scopes` array; the response includes a usable example body.
- Over-scoped registration fails cleanly with structured `denied_scopes`
  (requested scopes above the human's tier).
- `401` / `403` — missing, malformed, unknown, or revoked bearer (no
  `WWW-Authenticate` challenge yet; see Discover).
- `410` — device code already consumed or expired; restart at Register.
- `429` — per-token daily write limits (see https://www.immersivecommons.com/pricing.md for the
  table); back off until the next UTC day.

If a documented surface doesn't match the deployed behavior, POST a
structured report to https://www.immersivecommons.com/api/agent/feedback
(kinds: broken_url, schema_mismatch, stale_doc, endpoint_404, other).
Out-of-band: admin@immersivecommons.com.

## Revocation

- **Self-revoke (agent-driven):** POST https://www.immersivecommons.com/api/agent/token/revoke with
  the bearer to revoke — a token can kill only ITSELF (no Clerk session
  needed; cross-token revoke is deliberately not possible from a token).
  Returns `200 { ok: true, revoked: true, prefix }`. Idempotent.
- **Console revoke (human-driven):** the advertised
  `agent_auth.revocation_uri` — https://www.immersivecommons.com/floor10/agent-console — where the
  signed-in human can revoke ANY of their tokens.
- **Key rotation:** POST https://www.immersivecommons.com/api/agent/keys/revoke clears an Ed25519
  binding (then re-register a fresh key).
