SyntrumDocs
Open app

Approvals

When an agent wants to take an action that your rules say a human must sign off on, it stops and creates an approval. The Approvals queue is where you clear those decisions. Every card is a single action, paused mid-flight, waiting for your yes or no.

You reach it from the sidebar under Status → Approvals.

Approvals are the runtime enforcement point of Syntrum's governance. A guardrail or permission that resolves to "require approval" becomes a card here; a guardrail that resolves to "block" is refused outright and recorded in the Audit log. See The three planes for how those decisions are made.

Who can resolve approvals#

Resolving approvals — approve, reject, or edit-and-approve — is an Operator-and-above capability. Owners, Admins, and Operators can act on cards. Viewers can see the queue but cannot resolve anything. See Team & roles.

The layout#

The page is a two-pane review surface:

  • Left: the queue. The heading tells you how many decisions are waiting ("3 decisions to review"). Each card shows the action title, a short description, the agent that raised it, how long it's been waiting, and a risk badge.
  • Right: the selected approval in full — the tool it touches, the agent, the risk level, the full details, and the action payload (exactly what the agent proposes to do).

The queue refreshes on its own every few seconds, so newly raised approvals appear without a manual reload. When there's nothing to do, you get a calm "All caught up" screen.

Risk levels#

Every approval carries a risk level that sets the colour of its badge and helps you triage at a glance.

Risk Meaning
LOW Routine, low-impact action
MEDIUM Some impact — worth a look
HIGH Significant impact; review carefully
CRITICAL Highest impact; do not approve on autopilot

Why this needs you#

Under the description, many cards show a quiet caption with a shield icon — for example "Held by workspace policy", "Held by a tool pin", or "Held by agent policy". This is the policy provenance: it tells you which rule, at which level decided this action needed a human. The detail pane adds "— adjust it in the agent's Permissions tab" so you know exactly where to change the behaviour if it's asking too often (or not often enough).

Provenance is the answer to "why did my agent ask?" The three levels are workspace (the Safety floor every agent inherits), agent (a pin on this specific agent), and tool (a pin on one toolkit for this agent). Read more in Agent autonomy and Guardrails & sensitive actions.

Resolving an approval#

  1. Select a card in the queue to open it on the right.
  2. Read the Details and the Action payload — the payload is the literal action, so check recipients, amounts, and content.
  3. Click Approve to let the action run, or Reject to send it back. Either way the agent is unblocked and continues.

The card leaves the queue as soon as you act, and the decision is written to the audit log with your name against it.

Keyboard shortcuts#

The queue is built for speed. With a card selected:

Key Action
A Approve
R or S Reject
J Next approval
K Previous approval

Shortcuts are shown in a panel on each card (toggle with Show keys / Hide keys). They're suspended while you're typing in a field or editing a payload, so they never fire by accident.

Edit before approving#

Sometimes the agent has the right idea but a detail is off — a wrong recipient, a number to tweak, a sentence to rephrase. You don't have to reject and start over.

  1. In the Action payload box, click Edit & approve.
  2. Correct the payload in the editor. This must be the complete payload — it's a full replacement, not a merge.
  3. Click Approve with edits.

Your edited version is what executes. The original payload is preserved in the audit trail, so the record always shows both what the agent proposed and what you changed it to.

The editor expects valid JSON. If the syntax is broken you'll see "Invalid JSON — fix the syntax before approving" and nothing runs until it's fixed.

Edited approvals are also counted in the Reports Safety section as a "correction rate", so you can see how often your agents need a nudge before they get it right.

If an approval seems stuck#

If a card lingers longer than you expect, or the agent behaves as though it's still waiting after you approved, see the Troubleshooting guide.

What's next#