API reference

The gateway is a single endpoint. It accepts an intended action, returns a decision, and writes an immutable audit row. Authentication is the agent's scoped key (sk_live_…) in the body.

Endpoint

POST /api/gateway/actions, hosted at https://www.ifivo.com. On-prem customers point this at their own gateway host; the contract is identical.

Request

POST https://www.ifivo.com/api/gateway/actions
content-type: application/json

{
  "agent_api_key": "sk_live_…",
  "vendor": "stripe",            // string, required
  "action": "refund",            // string, required
  "amount_cents": 22000,         // integer, optional (required for spend policies)
  "risk_score": 0.55,            // number 0..1, optional
  "metadata": { "any": "json" }  // object, optional
}

Response

200 OK
{
  "ok":       true,                          // false when decision is "blocked"
  "decision": "allowed" | "pending_approval" | "blocked",
  "reason":   "human-readable explanation",
  "policy":   "slug-of-matched-policy" | null,
  "shadow":   null | { "decision": "...", "reason": "...", "policy": "..." },
  "tx":       "tx_…"                          // transaction id for the audit row
}

• decision is always one of three strings (allowed, pending_approval, blocked). Treat anything else as a 5xx retry candidate.
• ok is false when the decision is blocked and true otherwise. Convenient for short-circuiting on the client.
• shadow is populated when the matched policy is in shadow mode. The live decision is allowed, and the shadow block carries the would-have-been outcome.
• policy is the slug of the winning rule. Block-wins precedence applies when multiple policies match.
• tx is the audit-row id. Use it to look up the decision later via /app/transactions or the audit API.

Errors

400 Bad Request       // body failed validation
401 Unauthorized      // agent_api_key missing or unknown
403 Forbidden         // agent quarantined or org kill switch engaged
404 Not Found         // unknown route
429 Too Many Requests // rate limit on the org (see Retry-After header)
5xx                   // transient; retry with exponential backoff

Related endpoints

• POST /api/simulate: same engine, no audit write. Used by the public simulator.
• POST /api/approvals/:id/approve and /deny: human decisions on pending actions.
• POST /api/control/org/engage / /release: org-wide kill switch.
• POST /api/mcp: MCP server for ChatGPT, Claude, Gemini. See MCP docs.