API keys and service accounts
Give a script or an integration its own company credential — scoped to what it needs, shown once, revocable at once, and never able to sign a gate.
A script that starts runs every night, or a dashboard that reads the audit chain, should not borrow a person's session. Give it an API key instead: a company credential that acts for the company with the scopes you choose, and nothing more.
A machine never signs a gate. Whatever scopes a key holds, signing a gate needs a
person whose role allows it. POST /process-runs/{id}/resume with a key answers 403
"A machine cannot sign a gate."
Create a key
Only an owner or admin can create, list or revoke keys. In the admin, open
Settings → API keys, choose Create key, name it after what will use it, tick its
scopes, and optionally set an expiry date. The key (mk_live_…) is shown once, with a
Copy button. Store it in your secret manager right away; no screen or endpoint returns it
again. Minctrl keeps only its SHA-256 hash and the first 8 characters after mk_live_,
so you can tell keys apart in the list.
The same from the API, with an owner's or admin's session token:
curl -s -X POST "$API/api-keys" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "nightly-claims-import",
"scopes": ["runs:start", "runs:read"],
"expires_at": "2027-01-31T23:59:59Z"
}'The 201 response carries the key's fields plus secret. 422 means a blank name, no
scope or an unknown one, or an expiry in the past; 403 means you are not an owner or admin.
Scopes
| Scope | What the key may call |
|---|---|
runs:start | POST /process-runs — start a run of the published version of a saved process ("draft": true) or a bundled example. A key never runs an unpublished version, not even in shadow. |
runs:read | GET /process-runs, GET /process-runs/{id}. |
processes:read | GET /process-templates/, GET /process-templates/{vertical}/canvas, GET /process-templates/drafts, GET /process-templates/drafts/{slug}, its versions and diff. Test cases and suite results: GET /process-tests/{slug}/cases, …/runs, …/runs/{id}. A key never submits or publishes. |
processes:test | POST /process-tests/{slug}/runs, POST /process-tests/{slug}/compare — run a test suite against a version, never live. See Testing processes. |
audit:read | GET /audit-chain, /audit-chain/verify, /audit-chain/head, /audit-chain/export. |
processes:write | Reserved — accepted, no route uses it yet. |
triggers:manage | GET/POST /triggers, GET/PATCH/DELETE /triggers/{id}, POST /triggers/{id}/rotate — see Triggers. |
Every other route refuses a key with 403 "API keys cannot call this route." —
including key management itself, members, connectors and the governance policy. A route
the key may call but whose scope it lacks answers 403 "This API key does not have the
'…' scope."
Use a key
Send it as a bearer token, exactly like a session:
curl -s -X POST "$API/process-runs" \
-H "Authorization: Bearer $MINCTRL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"vertical": "claims-intake", "draft": true, "inputs": {"claim_id": "C-1042"}}'The run's created_by is key:<name> (here key:nightly-claims-import), and its
run_started audit entry names the key by id and name. The run then parks at its first
gate, where a person signs it in the sign-off queue as usual.
Autonomy is the company's, not the caller's. A run a key starts follows the same
autonomy policy as one a person starts: the gate
resolver clears the reversible low- and medium-risk steps it would clear anyway — that is
your company's own configured policy, not a signature. A gate the policy parks for a human
waits for a person who signs it through the sign-off card (or Slack); no audit entry ever
records a gate signature in a key (key:<name>)'s name.
Both SDKs take a key:
client = minctrl.MinctrlClient("https://app.minctrl.com", api_key=os.environ["MINCTRL_API_KEY"])
run = client.runs.start("claims-intake", inputs={"claim_id": "C-1042"}, draft=True)const mc = createMinctrl({ baseUrl: "https://app.minctrl.com", apiKey: process.env.MINCTRL_API_KEY });
// `draft: true` is not in the generated type yet.
const run = await mc.runs.start({ vertical: "claims-intake", draft: true, inputs: { claim_id: "C-1042" } } as StartRun);The Python client also reads MINCTRL_API_KEY from the environment when given neither a
token nor a key.
What a key's requests answer
| Status | Means |
|---|---|
401 "Invalid API key" | No key with that value exists. |
401 "This API key has been revoked" / "has expired" | The key was revoked, or its expires_at passed. |
403 | The route refuses keys, the key lacks the scope, or it tried to sign a gate. |
429 | The key went over its own rate limit — 120 requests a minute per key by default (API_KEY_RATE_LIMIT on the server). Wait for Retry-After seconds. |
503 "Could not verify the API key" | The key could not be read. Retry; the request was not let through. |
Each key has its own bucket, so one busy integration does not throttle another. The list shows Last used; it is updated at most once a minute.
Revoke a key
Settings → API keys → Revoke asks first, then stops the key at once: its next request
gets 401. From the API:
curl -s -X POST "$API/api-keys/$KEY_ID/revoke" -H "Authorization: Bearer $TOKEN"404 means no such key in your company; 409 means it is already revoked. A revoked key
cannot be restored — create a new one. The row stays, so runs the key started and audit
entries that name it still point at it.
In the audit chain
Creating a key writes api_key_created and revoking it writes api_key_revoked, each in
the same transaction as the change: who did it (user id and role), the key's id, name,
prefix, scopes and expiry, and for a revoke the state before. The secret and its hash are
never in the chain. If the entry cannot be written, the key is not created (or not revoked)
and the request answers 503.
Roles and permissions
Give people exactly what their job needs — custom roles built from named permissions, assigned to members, mapped from your IdP, named on gates, and audited with what changed.
Embedding and white-label
Put the sign-off queue or one run inside your own product with short-lived embed tokens, brand the widgets, emails and sign-in page as your company, and hear what happens to runs through signed webhooks.