ifivo
Docs · Reference

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
{
  "decision": {
    "outcome": "allowed" | "pending_approval" | "blocked",
    "reason":  "human-readable explanation",
    "policy":  "slug-of-matched-policy" | null,
    "shadow":  null | { "outcome": "...", "reason": "...", "policy": "..." }
  },
  "transaction_id": "tx_…"
}
  • outcome is always one of three strings. Treat anything else as a 5xx retry candidate.
  • shadow is populated when the matched policy is in shadow mode — the live outcome is allowed, and the shadow block tells you what would have happened.
  • policy is the slug of the winning rule. Block-wins precedence applies when multiple policies match.

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.