Sandbox / test environment

Exercise the Immersive Commons agent API without touching production data. Machine-readable descriptor (no auth): GET /api/sandbox. Markdown twin of this page: /sandbox.md.

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 (/api/mcp, /api/a2a, REST /api/*), same token format, same auth header — sandbox is a property of the token, not the URL.

Mint a sandbox token (self-serve)

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, they approve at /signup-with-agent, you poll /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

{
  "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 in sandbox.

Real vs simulated vs unavailable

Verb kindSandbox behaviour
Reads (list / get / search / status)Real production data
Writes with a concrete token scope (RSVP, book, submit highlight, set profile, …)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 catalogDenied (fail-closed) — never silently mutated

The unavailable writes fail closed: the sandbox denies anything it cannot prove it may safely simulate, rather than risk a real mutation. The live deny/allow lists are enumerated in the machine descriptor.

Links