# Sandbox / test environment — Immersive Commons

Exercise the Immersive Commons agent API without touching production data.

## What the sandbox is

A **sandbox token** is a normal `agt_` bearer minted through the same
human-approved device-code flow (RFC 8628) with one flag flipped:
`"sandbox": true`. It carries real scopes and authenticates like any token.
The only difference is post-auth mutation routing: **write** verbs validate +
scope-check as usual but return a **simulated receipt** instead of mutating
production state; **reads serve real production data**.

Same endpoints (`https://www.immersivecommons.com/api/mcp`, `https://www.immersivecommons.com/api/a2a`, REST `/api/*`), same
token format, same auth header — sandbox is a property of the **token**, not
the URL.

## Probe it (no auth required)

`GET https://www.immersivecommons.com/api/sandbox` returns the machine-readable descriptor: what
sandbox simulates, which endpoints honor it, and the fail-closed rules.

## Mint a sandbox token (self-serve)

```bash
curl -X POST https://www.immersivecommons.com/api/agent/signup/start \
  -H 'content-type: application/json' \
  -d '{"scopes":["events:read_upcoming","events:rsvp"],"client_name":"my-agent (sandbox)","sandbox":true}'
```

Complete the device-code flow exactly as normal: show your human the
`user_code` + `verify_url_complete`, they approve at
https://www.immersivecommons.com/signup-with-agent, you poll `https://www.immersivecommons.com/api/agent/signup/poll` until
`status:"completed"`. The completion response echoes `"sandbox": true`.

**The flag is immutable after mint.** No endpoint upgrades a sandbox token to
a live one — production write access means minting a new token through the
same human approval.

## What a simulated write returns

```json
{
  "ok": true,
  "sandbox": true,
  "simulated": true,
  "would_have": { "action": "ic_events_rsvp", "scope": "events:rsvp", "args": { "...": "..." } },
  "note": "Sandbox token — scope-checked; deeper business rules (tier / role / ownership / signature) are not evaluated in sandbox, and no production state was changed. Mint a non-sandbox token to perform this for real."
}
```

A green sandbox receipt means "well-formed and scoped," **not** "guaranteed to
succeed in production" — the deeper business-rule gates (live tier, role,
ownership, signature) are not evaluated.

## Real vs simulated vs unavailable

| Verb kind | Sandbox behaviour |
|---|---|
| Reads (list / get / search / status) | **Real** production data |
| Writes with a concrete token scope (RSVP, book, submit, …) | **Simulated** receipt, no mutation |
| `ic_feedback_submit` (bug-report channel) | **Real** — a sandbox agent that finds a real bug must be heard |
| Token self-revoke (`POST /api/agent/token/revoke`) | **Real** — token lifecycle, not floor data |
| `ic_donate` (x402 USDC payment), role-gated admin toggles, tools not yet in the scope catalog | **Denied** (fail-closed) — never silently mutated |

## Links

- Machine descriptor: https://www.immersivecommons.com/api/sandbox
- Developer portal: https://www.immersivecommons.com/developers (§ 06 Sandbox)
- Auth walkthrough: https://www.immersivecommons.com/auth.md
- Rate limits + $0 pricing: https://www.immersivecommons.com/pricing.md
- OpenAPI 3.1 spec: https://www.immersivecommons.com/openapi.json