ifivo
Docs · Reference

Policy language

ifivo policies are JSON. A policy has a name, an array of rules (ANDed together), and an action to take when all rules match. There is no DSL to learn, no LLM in the hot path, and the engine is deterministic.

Supported fields

  • vendor: string. Examples: stripe, aws, openai, google-ads.
  • action: string. Whatever you send; typical values are refund, charge, provision, api_call.
  • amount_cents: integer.
  • risk_score: number 0..1.
  • vendor_first_seen: boolean, computed per-agent by the gateway.
  • metadata.*: dot-pathed access into the metadata object you send.

Operators

eq, gt, gte, lt, lte, in, not_in. These are enum strings. Symbolic forms like > or >= are not accepted by the policies API.

Semantics

  • Within a policy: all rules must match (AND).
  • Across policies: every matching policy contributes. If any returns block, the request is blocked. Block wins.
  • Otherwise, if any matching policy requires approval, the outcome is pending_approval.
  • If nothing matches, the outcome is allowed.

Shadow mode

Setting shadow: true on a policy makes it observe-only. The policy runs, the matched decision is recorded on the gateway response under shadow, but the live outcome is unchanged by that policy. Use shadow mode to roll out a new rule, inspect the would-be decisions in transactions, and flip to enforcement once the thresholds are right.

Policy shape

  • name: required string, shown in the dashboard.
  • rules: required non-empty array. Each rule has field, op, value, and an action (allow, block, or require_approval).
  • action: optional policy-level action. When set, it overrides the first rule's action on whole-policy match. Defaults to require_approval.
  • shadow, enabled, priority, description: optional, self-explanatory.

Examples

These are the three policies loaded in the public simulator.

{
  "name": "Refunds over $150 require approval",
  "rules": [
    { "field": "action",       "op": "eq", "value": "refund", "action": "require_approval" },
    { "field": "amount_cents", "op": "gt", "value": 15000,    "action": "require_approval" }
  ],
  "action": "require_approval",
  "shadow": false
}
{
  "name": "AWS provision blocked by default",
  "rules": [
    { "field": "vendor", "op": "eq", "value": "aws",       "action": "block" },
    { "field": "action", "op": "eq", "value": "provision", "action": "block" }
  ],
  "action": "block",
  "shadow": false
}
{
  "name": "High risk requires approval",
  "rules": [
    { "field": "risk_score", "op": "gte", "value": 0.8, "action": "require_approval" }
  ],
  "action": "require_approval",
  "shadow": true
}

Authoring policies

Most teams start from a template, tune thresholds in shadow mode, then flip to enforcement. The visual builder at Policies → New produces the exact JSON shown above.