Minctrl Docs
Guides

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

ScopeWhat the key may call
runs:startPOST /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:readGET /process-runs, GET /process-runs/{id}.
processes:readGET /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:testPOST /process-tests/{slug}/runs, POST /process-tests/{slug}/compare — run a test suite against a version, never live. See Testing processes.
audit:readGET /audit-chain, /audit-chain/verify, /audit-chain/head, /audit-chain/export.
processes:writeReserved — accepted, no route uses it yet.
triggers:manageGET/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

StatusMeans
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.
403The route refuses keys, the key lacks the scope, or it tried to sign a gate.
429The 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.

On this page