API and MCP

Base URL https://shuttlewright-trust-gateway.pillar-3a8.workers.dev. JSON in, JSON out, CORS open. Max body 8 KB.

Create a grant (owner)

POST /api/v1/grants {"owner":"Ama","agent":"ops bot","expires_in_minutes":60, "scopes":[{"action":"files.*"},{"action":"email.send"}, {"action":"purchase","max_amount":100,"hold_above":25}, {"action":"files.delete"}]} -> {grant:{id:"gr_..."}, owner_token:"ot_...", receipt:{...}}

The grant id is the agent's credential. The owner token is shown once and is needed to approve, deny and revoke. A scope action is exact (email.send) or a wildcard (files.*). Money actions need max_amount.

Check an action (agent)

POST /api/v1/check {"grant_id":"gr_...","action":"purchase","target":"shop.example","amount":60,"description":"annual license"} -> {decision:"hold", reason:"over_hold_threshold", reversibility:"hard", approval_id:"ap_...", approval_url:"...", receipt:{payload,signature,hash}}

Proceed only on allow. On hold, stop. After the owner approves, call again with approval_id. An approval is single use and bound to the same action, target and amount.

Approve or deny (owner)

POST /api/v1/approvals/{ap_id}/decide {"decision":"approve","owner_token":"ot_..."} GET /api/v1/approvals/{ap_id} POST /api/v1/grants/{gr_id}/revoke {"owner_token":"ot_..."}

The approval_url opens a page where the owner pastes the token and decides.

Receipts and verification

GET /api/v1/grants/{gr_id}/receipts all receipts plus chain status POST /api/v1/verify {"receipts":[...]} signature, hash and chain check GET /.well-known/jwks.json Ed25519 public key (kid in each receipt)

Signature is Ed25519 over the canonical JSON of payload (keys sorted, no spaces). hash is SHA 256 of the canonical payload, a dot, then the signature. prev_hash in each payload is the previous receipt's hash. You can verify offline with the public key.

Action classes

Unknown actions are classed irreversible. The agent may send a stricter reversibility value, never a looser one.

MCP connector

Stateless streamable HTTP at /mcp (JSON-RPC 2.0). Tools: check_action, get_approval, verify_receipt, list_actions.

{"mcpServers":{"trust-gateway":{"url":"https://shuttlewright-trust-gateway.pillar-3a8.workers.dev/mcp"}}}

Tell your agent: "Before any action that changes something, call check_action with my grant id. Only act on allow." The gateway cannot force an agent to ask.