Your first governed flow
From zero to a completed governed run — write a small process, validate it, save it, run it, watch it park at a human gate, sign it, and read the audit chain — with the reason behind each step.
This tutorial takes you from nothing to a completed governed run of a process you write yourself, and explains why each step exists. You will write a four-step refund process, see validation reject an ungoverned version of it, save it, run it, sign its gate, and read the record the run leaves behind.
The Quickstart is the shorter path (it imports a ready example); Example processes are larger flows to import and run. This page stops at each step to explain the idea behind it.
What you need
A Minctrl API base URL in $API, and curl + jq. Registration creates everything else.
Why governance, not just automation
Automating a regulated process usually forces a bad trade: either a person touches every step (slow, expensive) or agents run unsupervised (fast, hard to defend). Minctrl lets agents do the reversible work and parks the run for a human verdict on the steps that can't be undone. Everything that happens is written to a hash-chained audit record.
Step 1 — Register
TOKEN=$(curl -s -X POST "$API/auth/register" \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]","password":"<your-password>","company_name":"Acme Ops"}' \
| jq -r .token)Why it matters. Registration creates a company and makes you its owner. The company is the isolation boundary: your token identifies both you and your company, and every process, run and audit entry you create belongs to it. A new company starts with no processes — the next steps add the first one.
Step 2 — Write the process
A process is a graph of nodes (steps) and edges. This one checks a refund request, asks a finance manager to approve it, then issues the refund:
cat > refund.json <<'EOF'
{
"nodes": [
{ "id": "__start__", "kind": "terminal" },
{ "id": "check", "kind": "agent", "label": "Check the refund against policy",
"tier": "low", "reversible": true, "tools": [] },
{ "id": "signoff", "kind": "gate", "label": "A finance manager approves the refund",
"human": "Finance manager", "gate": "gate:refund-signoff",
"tier": "high", "reversible": false, "interrupt_before": true },
{ "id": "pay", "kind": "agent", "label": "Issue the refund",
"tier": "high", "reversible": false, "tools": ["payments"] },
{ "id": "__end__", "kind": "terminal" }
],
"edges": [
{ "source": "__start__", "target": "check" },
{ "source": "check", "target": "signoff" },
{ "source": "signoff", "target": "pay" },
{ "source": "pay", "target": "__end__" }
]
}
EOFWhy it matters. The graph that drives execution also carries the governance: each step
has a risk tier and a reversible flag, and the gate node names the human role
(human) and the gate id (gate) a run will park on. pay is irreversible — money that
left can't be called back — so it sits behind the gate.
Step 3 — Validate (why a flow can't be silently ungoverned)
curl -s -X POST "$API/process-templates/validate" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
--data-binary @refund.json | jq .violations[]Now remove the gate and connect check straight to pay:
jq '.nodes |= map(select(.id != "signoff"))
| .edges = [{"source":"__start__","target":"check"},
{"source":"check","target":"pay"},
{"source":"pay","target":"__end__"}]' refund.json \
| curl -s -X POST "$API/process-templates/validate" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
--data-binary @- | jq .violations["step None_1 ('Issue the refund'): irreversible action not preceded by a human gate"]Why it matters. Validation enforces the invariants that make governance real: an
irreversible step must have a human gate in front of it, and a gate must carry its human
role and gate id. A process with violations can be saved as a draft, but a run of it is
refused with 422 — so an ungoverned flow can't run by accident. (See
Design on the canvas.)
Step 4 — Save it
jq '{slug: "refund-approval", name: "Refund approval"} + .' refund.json \
| curl -s -X POST "$API/process-templates/" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
--data-binary @- | jq '{slug, version, violations}'Why it matters. Each save is a new immutable version of (company, slug), and it is
a draft: it does not run for real until it is published (Step 5). A run is
pinned to one version for its whole life, so editing the process later never changes a run
that is already waiting for a signature. GET /process-templates/drafts lists the latest
version of every process in your company, its state, and published_version.
Step 5 — Publish it
Working through this tutorial alone, turn separation of duties off first: with it on (the default) the author of a version may not publish it, and you are the author.
curl -s -X PUT "$API/governance/policy" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -d '{"separation_of_duties": false}'
curl -s -X POST "$API/process-templates/drafts/refund-approval/versions/1/submit" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -d '{"note": "First version of the refund flow."}'
curl -s "$API/process-templates/drafts/refund-approval/diff?version=1" \
-H "Authorization: Bearer $TOKEN" | jq '{against, changes, steps: .steps.added | length}'
curl -s -X POST "$API/process-templates/drafts/refund-approval/versions/1/publish" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" -d '{"against": null}' | jq '{version, state, sod, by_author}'Why it matters. Runs start only from the published version, so a change to what
the autopilot does is a decision someone signs off. In a team you keep separation of duties
on and the person who changes the process is not the one who publishes it: another owner or
admin reads the diff and publishes (your own publish is then refused with 403). Alone,
the entry records "sod": false, "by_author": true — the record says plainly that the
author published it. Before publishing, the author can also test a version as a shadow
run ("draft_version": 1, "shadow": true). See
Publishing processes.
Step 6 — Run it (the autopilot does the reversible work)
RUN=$(curl -s -X POST "$API/process-runs" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"vertical": "refund-approval",
"draft": true,
"inputs": { "order_id": "O-1001", "amount": 120 }
}')
RUN_ID=$(echo "$RUN" | jq -r .id)
echo "$RUN" | jq '{status, parked_at, step: .trace.parked_step, graph_version, graph_hash}'Why it matters. vertical is your process slug and draft: true says it is a process
saved in your company; the run starts from its published version. With auto_resolve (on
by default) the resolver executes the steps it can clear — here, check — and stops at the
first step that needs a person. The response records which version and hash the run is
pinned to.
Step 7 — The gate: why the run parks
The run came back with status: "awaiting_human", parked_at: "gate:refund-signoff" and
trace.parked_step: "signoff".
Why it matters. The run reached a gate whose step is irreversible, so it parks: its state is persisted and it waits. Parking is durable, so it can wait minutes or days without holding a request open — a governed process fits a real person's working day instead of a timeout.
Step 8 — Sign the gate
curl -s -X POST "$API/process-runs/$RUN_ID/resume" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{ "gate": "signoff", "decision": "approved", "feedback": "Within policy." }' \
| jq '{status, parked_at}'Why it matters. Signing needs the manager role or above; your role is recorded with the
signature. The verdict is recorded against the gate and the run continues from there — steps
that already ran are not called again. pay now executes, in shadow (no real payment)
because no connector has opted the payments tool in, and the run reaches completed.
Name the gate by its step-id (signoff) or its parked_at label (gate:refund-signoff).
A gate that names neither leaves the run parked on the same gate, so check status and
trace.parked_step in the response.
Step 9 — The audit chain: why it's all defensible
curl -s "$API/audit-chain?run_id=$RUN_ID" -H "Authorization: Bearer $TOKEN" \
| jq '[.[] | {seq, kind}]'
curl -s "$API/audit-chain/verify" -H "Authorization: Bearer $TOKEN"Why it matters. The run start and every signature are entries in your company's audit
chain, written in the same transaction as the change they record; saving and importing
processes are recorded too. Each entry is hash-linked to the one before, so verify reports
the first entry that was edited or deleted. The run's own trace.events (from
GET /process-runs/{id}) shows each step: what auto-executed, what parked, who signed.
What you built
A process you wrote and published, where an agent did the reversible work, a person signed the step that can't be undone, and the whole run left a verifiable record:
write → validate → save → submit → publish → run → gate → park → sign → auditWhere to go next
- Connect a step to your API — point the
paymentstool-id at your real system, and keep irreversible tools shadowed until you opt in. - Configure gates and autonomy — what auto-clears and what always waits for a person.
- Example processes — import AML, collections and chargeback flows and run them.
Quickstart
Register, import an example process (or save your own), publish it, start a run that parks at a human gate, then sign the gate — with curl for every step.
Connect a step to your API
Bind a step's tool-id to a real HTTP endpoint with a connector, map inputs, and control shadowing of irreversible tools.