Minctrl Docs
Guides

Escalation, delegation and N-of-M approvals

Require several signatures on a gate, hand your gates to a delegate while you are away, assign a waiting gate to a named member, and let a deadline's escalation level reassign it — without anything ever signing or rerouting a run on its own.

Four tools for the moment a gate waits on the wrong person, or on one person when it should wait on two:

ToolWho uses itWhat it changes
N-of-M approvalsthe process author, on the gatehow many people must sign before the run continues
Out of officeany member, for themselveswho is told about their gates while they are away
Assigna manager, admin or ownerwho a waiting gate is pointed at
SLA level actionsthe process author, on the deadlinewhat an escalation level does besides notifying

None of them signs a gate, refuses a verdict on its own, or reroutes a run. Every change is recorded in the audit chain.

N-of-M approvals

A gate may declare an approvals policy:

{
  "id": "release",
  "kind": "gate",
  "label": "Release the funds",
  "human": "treasury",
  "gate": "gate:funds-release",
  "tier": "high",
  "approvals": { "required": 2, "distinct_people": true, "order": "any" }
}
FieldMeaning
requiredHow many approvals clear the gate, 1 to 10. One is the plain gate.
distinct_peopleDefault true: each approval comes from a different person. A delegate who signs for someone counts as both of them.
orderany (default) — in any order; sequential — approval k comes from a holder of roles[k].
rolesOptional for any: the roles that may approve (owner, admin, manager). Required for sequential: one role per approval, in order.

On the canvas, select the gate and press Require several in the inspector. A policy that is not valid is refused when you save (422 with violations naming the step) and reported live while you edit; a run never starts on it. It round-trips through the JSON export and through BPMN as a minctrl:approvals extension element next to the gate's form.

Signing an N-of-M gate

Each person signs through the same door as any gate — the sign-off card, the API, never Slack:

curl -s -X POST "$API/process-runs/$RUN/resume" \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"gate": "release", "decision": "approved", "feedback": "Checked the payee."}'
  • An approval short of quorum is recorded in the run's decisions and as a gate_approval_recorded audit entry (who, role, note, recorded of required). The run stays awaiting_human; the response carries approvals:

    { "status": "awaiting_human",
      "approvals": { "state": "read", "required": 2, "order": "any",
                     "signed": [{ "by": "[email protected]", "role": "manager", "at": "…", "verdict": "approved" }],
                     "next_roles": null } }
  • The approval that reaches quorum records the verdict: one gate_signed entry with every approval in approvals.signed, and the run continues. On the durable runtime the workflow receives one signal, at quorum, carrying every approval.

  • A denial by anyone ends the gate at once and follows its deny outcome. It still states its reason.

  • Approvals that name a branch must all name the same one (409 otherwise).

The sign-off card shows "1 of 2 signed" and who signed (and for whom). When the approvals could not be read it says Approvals: not read — never "0 of 2".

RefusalWhen
409You already approved this visit of the gate (distinct_people), or a delegate already approved it for you.
409Separation of duties is on and you started the run (or you sign for the person who did).
403The policy names roles, and yours is not the one this approval needs (sequential: "Approval 1 of 2 needs manager").
409Another signature landed on the run between your read and your write — refresh and sign again.
503The audit entry could not be written: nothing was recorded.

Separation of duties still applies across gates: an approval is a signature, so a person who approved one gate of a run cannot sign a different gate of it.

A gate that needs more than one signature is never offered as buttons in Slack; its message has one Open in Minctrl button.

Out of office

On Settings → Out of office (/settings/delegation), name a delegate and a period. While it runs:

  • the gate notices meant for you — a gate parked, an SLA level, an assignment — go to the delegate instead, on their channels. Their message says it is for you;
  • the delegate may sign only when their own role allows. Their signature's audit entry names you both: "by": "<delegate>", "on_behalf_of": ["<you>"].
curl -s -X POST "$API/delegations" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"delegate_email": "[email protected]", "starts_at": "2026-11-02T08:00:00Z", "ends_at": "2026-11-09T08:00:00Z"}'
RefusalWhen
422Yourself, someone who is not an active member, a period that ends before it starts, is over, or is longer than a year.
409It overlaps another delegation of yours.
409It would send your gates back to you through a chain of delegations in that period.
403A machine (API key, trigger) tried to set one.

GET /delegations lists yours (mine) and those made to you (to_me); DELETE /delegations/{id} ends one now (its member, or an owner or admin). Both are audited (delegation_set, delegation_revoked). A delegate whose role cannot sign gates is still told — the page says so when you save.

Assign a waiting gate

A manager, admin or owner assigns the gate a run waits at to a named member from the sign-off card (Assign), or over the API:

curl -s -X PUT "$API/process-runs/$RUN/assignment" -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"email": "[email protected]", "note": "Bo owns fraud this week"}'

The member must be able to sign it — their role, separation of duties (not the run's starter, not someone who signed another gate of the run) and the approvals so far. The picker (GET /process-runs/{id}/assignees) lists every member with whether they may take it and, if not, why. An assignment is recorded as gate_reassigned and the member is notified (gate_assigned). The queue row and the card show Assigned to [email protected] · by [email protected]. DELETE …/assignment clears it (audited).

By default an assigned gate can still be signed by any eligible signer — the assignment directs the notices. An owner or admin can turn on Only the assignee signs under Settings → Governance (PUT /governance/policy {"only_assignee_signs": true}, audited): an assigned gate is then signed only by its assignee or their delegate (403 for anyone else). The switch applies to single-approval gates; an N-of-M gate always needs N people.

SLA level actions

A step's deadline (sla_spec) escalates at fractions of its time (escalate_at), and each level sends its notice through the notifications fan-out. Each level may now say what it does:

"sla_spec": {
  "amount": 2, "unit": "days", "calendar": "business",
  "escalate_at": [0.5, 0.75],
  "level_actions": [
    { "at": 0.5,  "action": "reassign_to_role", "role": "admin" },
    { "at": 0.75, "action": "assign_to_user", "user": "[email protected]" }
  ]
}
actionWhat the level does
notifyWhat every level always did: tell the roles in notify_roles, else the people who may sign.
reassign_to_roleTell that role and mark the gate as assigned to it.
assign_to_userAssign the gate to that member and tell them. If they cannot be found or may not sign it, the level records sla_action_failed with the reason and notifies as notify would.

The sla_escalated entry names the action; an assignment it made is a gate_reassigned entry with "by": "sla". A level never signs the gate and never changes where the run goes next.

On this page