Approvals

​

The flow

1. The agent makes the call. Reversi queues an approval request and blocks the call. The message names the request id: approval required: request apr_… is pending an operator decision; retry after it is approved.
2. An approver decides it: in the console, with reversi approvals approve <id>, over the HTTP API, through the gateway’s operator endpoint, or from a Slack button. A notification can tell them first.
3. The agent retries the same call with the same arguments. The approval is consumed, the call runs, and the ledger records approved.

reversi approvals list -d ./reversi-data
# apr_4442c0ff-…  pending  run=r1  call  payments.refund  args=[amount,order]  why: policy `big-refund`: large refund; manifest requires approval
reversi approvals approve apr_4442c0ff-… -d ./reversi-data --as fiona --groups finance --note ok

​

What an approval is bound to

• The arguments. A call approval carries the hash of the arguments it was requested for. Approve a refund of 5 and a retry for 500 is a different call and needs its own approval.
• One use. After the call runs the approval is consumed. Running the same call again queues a new request.
• A time limit. Pending and approved requests expire (default one hour, approval.ttl in reversi.config.yaml, or the timeout set by the manifest or rule).
• A decision record. Who decided, when, the basis (role, group or delegation) and the note, in the approval store. The ledger also gets a record, whichever way the decision is made (CLI, server, gateway or console): approved for approvals, blocked for denials, with the approver as actor.
• Claimed atomically. Consuming or deciding a request is a compare-and-swap in the store, so two processes sharing a database cannot both use one approval or both cast the last vote.
• A denial sticks for that call (same arguments, same step), with the reason shown to the agent.

​

Who may approve: routing and quorum

- tool: payments.refund
  effect: reversible
  permission: payments:write
  approval:
    roles: [finance]          # Reversi roles or group names
    quorum: 2                 # distinct approvers needed, 1 to 10
    timeout: 15m
    on_timeout: escalate      # deny (default) or escalate
    escalate_to: [admin]

rules:
  - id: big-refund
    match: { tool: "payments.refund" }
    when: [{ path: $args.amount, op: gt, value: 500 }]
    action: require_approval
    approvers: [finance]
    quorum: 2
    approval_timeout: 30m
    on_timeout: escalate
    escalate_to: [admin]
    reason: large refund

• Roles and groups. An approver qualifies if they hold a listed role, or belong to a listed group. Groups come from groups on an API key or, for OIDC, from the values of the role claim.
• Several requirements on one call (manifest plus rules) are merged: any listed role may approve, the largest quorum wins, the shortest timeout wins, and deny on timeout wins over escalate.
• Quorum. Each approver counts once. One denial ends the request. A quorum above 1 needs roles. While votes are missing the request stays pending and the message says needs 2 approvers from finance.
• No self-approval. Whoever owns the run that asked cannot decide the request.
• Deciding as a group member. Over HTTP and in the console your key’s groups are used. With the CLI you state them: --groups finance and --roles operator (default operator). A person who is not in the group is refused: this request needs an approver from: finance. The CLI trusts the caller, so use it on the host that owns the data.
• The open console acts as one role and has no groups, so it can decide only requests that name that role or no one.

​

Escalation on timeout

​

Delegation

reversi delegate add --from fred --to dan --hours 24 --reason "on leave" --group finance -m tools.yaml -d ./reversi-data
reversi delegate list -m tools.yaml -d ./reversi-data
reversi delegate revoke dlg_… -m tools.yaml -d ./reversi-data

• Who and how long. --from, --to, a reason (required), and an end time at most 90 days away. You cannot delegate to yourself.
• Scope. --group (repeatable) limits it to requests routed to those groups. Without it the delegation covers every routed request, so always pass --group.
• What happens. The delegate approves as themselves; the decision records on_behalf_of and the basis delegated by fred (finance). It counts as fred’s vote: fred cannot vote on the same request afterwards, and the delegate cannot vote twice. The delegate still needs the approver role to reach the approve endpoint.
• Ends at its expiry or when revoked.
• Where. The CLI above, the Approvals page of the console (own authority, hours and reason), or the /v1/delegations endpoints, which reversi-server serves (admin API). Delegations apply everywhere a decision is made, including reversi approvals approve --as <delegate>.

​

Break-glass

reversi break-glass apr_… --reason "payments outage, customer escalated" --evidence INC-77 --by root -m tools.yaml -d ./reversi-data

curl -X POST -H "Authorization: Bearer $ADMIN_KEY" -H 'content-type: application/json' \
  -d '{"reason":"customer is waiting on the line","evidence":"INC-42"}' \
  http://localhost:7421/v1/approvals/apr_…/break-glass

• Admin only over HTTP and in the console (other roles get 403). A reason of at least 10 characters and a pointer to evidence (ticket or incident) are required (400 otherwise). The CLI has no login, so it accepts --by as given.
• Recorded. The approval keeps break_glass with who, why, the evidence reference and the time. The ledger gets an approved record whose detail starts BREAK-GLASS: … evidence: INC-77.
• Notified. A critical break_glass notification goes out, and a critical break_glass alert shows in the console.

​

What the approver sees

​

Notifications

​

Approving from Slack

createApp({ /* … */ slack: { signing_secret, users: { U123: { name: "fiona", roles: ["approver"], groups: ["finance"] } } } });

​

Pre-approval

​

Who can decide

​

Storage