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.
Your users sign gates where they already work — inside your product — and never sign in to Minctrl. Your backend mints a short-lived embed token for the signed-in user; your page mounts a widget in an iframe; the widget signs as that user's Minctrl membership and nobody else, through the same rules as the console. Your product hears every run event through webhooks, and everything the user sees carries your branding.
The pieces
| piece | where | who |
|---|---|---|
| Allowed origins | Settings → Embedding | changed with settings.governance (owner, admin); read with it or api_keys.manage |
| Embedded signing | Settings → Embedding | each member for themself; the company's allow-list with settings.governance |
Embed keys (embed:issue) | Settings → Embedding or API keys | api_keys.manage |
| Embed tokens | POST /embed/tokens from your backend | an embed:issue key |
| Widgets | /embed/signoff, /embed/run/<id> in your iframe | the SDK @minctrl/embed |
| Branding | Settings → Branding | company.update |
| Host webhooks | Settings → Webhooks | notifications.manage |
Every change to origins, embedded signing, branding and webhooks, and every token minted, is in
the audit chain (embed_origins_changed, embed_signing_changed, embed_token_issued,
branding_changed, host_webhook_*).
1. Allow your origin
Add the origin of the page that frames the widget — https://portal.example.com (scheme, host,
port; no path, no wildcard; http:// only for localhost). The widget pages are served with
Content-Security-Policy: frame-ancestors 'self' https://portal.example.com; …so a browser refuses to show them on any other page. The policy names only the page framing
the widget (read from its Referer — the SDK's iframe sends its origin with
referrerpolicy="origin"; a hand-made iframe must not set no-referrer), when it is allowed:
the public GET /embed/frame-policy?company=…&origin=… answers yes or no for that one origin and
never lists a company's origins. Every other page of Minctrl is served with
X-Frame-Options: DENY. Removing an origin ends every widget session opened from it at once.
2. Mint a token on your backend
Create a key with only the embed:issue scope. It mints tokens and does nothing else: it
cannot start, read or sign anything itself — a machine never signs.
curl -X POST https://app.minctrl.com/api/embed/tokens \
-H "Authorization: Bearer $MINCTRL_EMBED_KEY" -H "Content-Type: application/json" \
-d '{"user_email": "[email protected]", "view": "signoff", "process": "claims-review",
"permissions": ["embed.view", "embed.sign"], "ttl_seconds": 600}'{ "token": "met_…", "view": "signoff", "permissions": ["embed.view", "embed.sign"],
"origins": ["https://portal.example.com"], "expires_in": 600, "member": true,
"embed_url": "/embed/signoff?c=<company>#token=met_…" }user_email— your signed-in user. Withembed.signthey must be an active member of the company (422 otherwise) who allows embedded signing (403 otherwise): the token signs as that member. Each member turns it on for themself on Settings → Embedding (“Allow host products to let me sign inside their pages”), or someone holdingsettings.governanceputs them on the company's allow-list; turning it off stops the member's open widget sessions from signing at once. Anyone else gets a view-only token (embed.view); the audit entry names them by email domain only.- A person (
api_keys.manage, to test) may mint only for their own email — never for a colleague (403) — andembed.signalso needsgate.approve. One person can therefore never stand in for another and satisfy separation of duties or an N-of-M gate twice. view—signoff(the queue of one process: name it inprocess; setall_processes: trueto cover every process's gates — 422 otherwise) orrunwithrun_id. A shadow test run is never embedded. The widget shows who started and signed a run by name ("you" for the token's member, "a colleague" without a name) — never by email.ttl_seconds— 30–900. A token lives at most 15 minutes (the database refuses longer) and is exchanged once.origin— optional: bind the token to one allowed origin.
Only the token's SHA-256 is stored. Never send the key to a browser.
3. Mount the widget
import { Minctrl } from "@minctrl/embed"; // packages/embed-sdk — no dependencies, typed
const widget = Minctrl.mount(document.getElementById("approvals"), { token, view: "signoff" });
widget.on("signed", (e) => refresh(e.run_id)); // { run_id, gate, decision, status }
widget.on("error", (e) => { if (e.code === "expired") remount(); });The SDK puts the token in the iframe URL's fragment — browsers never send a fragment to a
server, so it is in no log — and the company id in the query, so the page can be served with
your CSP before the token is used. The widget removes the token from the address bar, exchanges
it (with the origin of the page framing it, which must be one the token is bound to) for a
session it keeps in memory — no cookie — and talks to your page with postMessage, only to
that origin:
| event | data |
|---|---|
minctrl:ready | { view } |
minctrl:resize | { height } — the SDK sizes the iframe |
minctrl:signed | { run_id, gate, decision, status } |
minctrl:error | { code, message } — expired, unauthorized, forbidden, not_found, conflict, invalid, server, network |
The SDK accepts messages only from the iframe it mounted and only from Minctrl's origin.
What signing in the widget checks
The widget calls the one sign door, sign_gate, on the embed channel, as the mapped
member — the request cannot name another signer. Everything the console enforces applies:
- the member's role holds
gate.approve(andgate.approve.high_tierfor a live irreversible action); - separation of duties — someone who signed another gate of the run is refused;
- the gate's form is validated server-side (422 naming the field);
- an N-of-M gate counts the signature as one approval;
- a refusal needs a reason;
- a signature that authorizes a live irreversible action needs the gate id typed — on
this channel the server checks it (
confirm), not only the screen.
The gate_signed entry records channel: "embed" and the token that was used.
Settings → Embedding → Test embed preview frames the sign-off widget from Minctrl itself with a five-minute, view-only token for you.
4. Brand it
Settings → Branding:
| field | rule |
|---|---|
| Display name | 1–80 characters; shown instead of “Minctrl”. |
| Primary colour | #rrggbb with at least 4.5:1 contrast against the page and button text token (--sheet, #f7f7f7) — a colour that would not read is refused, with its ratio. |
| Support email | shown as “Questions? …”. |
| Email sender name | a name only — emails always come from the server's own address, so SPF and DKIM keep holding. |
| Logo | PNG, JPEG or WebP, ≤ 256 KiB, ≤ 2048 px a side. Its type is read from its bytes. SVG is refused (it can carry script); the logo is served with its own type, nosniff and default-src 'none'. |
The branding shows in:
- the embed widgets (name, logo, colour on the primary buttons);
- the notification emails (the gate digest: name in the subject and sign-off, logo and colour in the header, support email in the footer, the sender name in front of the server's address);
- the sign-in page reached through your SSO domain —
https://app.minctrl.com/?sso=acme.comshows your name and logo, only for a domain your company has verified on Settings → SSO.
5. Hear what happens: host webhooks
Settings → Webhooks → Add a webhook: a name, your endpoint and the events —
run.started, run.parked, gate.signed, run.completed, run.failed. The signing secret is
shown once (rotate it any time) and stored sealed.
Each event is recorded in the same transaction as the change it describes (a run that did not start has no event; an event that could not be recorded means the start did not happen either) and POSTed one at a time, in order:
POST /minctrl/events
Content-Type: application/json
Minctrl-Event: gate.signed
Minctrl-Delivery: 5f0c… (the event id — de-duplicate on it)
Minctrl-Signature: t=1762000000,v1=… (HMAC-SHA256 of "<t>.<raw body>" with the secret)
{"id":"5f0c…","type":"gate.signed","seq":3,"company_id":"…","created_at":"…",
"data":{"run_id":"…","process":"claims-review","step":"signoff","decision":"approved",
"by":"[email protected]","channel":"embed","status":"completed"}}The signature is the same scheme as inbound triggers: verify it with
the same code, and refuse a t older than five minutes. Run inputs are never sent.
- At least once, never out of order. A webhook's cursor moves only after your endpoint
answers 2xx for that event; anything else is retried with exponential backoff and jitter
(5 s, 10 s, 20 s … up to 5 min). An event may arrive twice — de-duplicate on
Minctrl-Delivery. - Failing. A webhook whose failures last an hour is marked failing (shown on the page;
host_webhook_failingin the audit chain, once) and recovered when it accepts again. - Delivery log. Every attempt — event, status code or error, duration — is on the page;
Send test posts a signed
webhook.testwithout touching the cursor. - A new webhook starts from now; a turned-off one keeps its place and catches up when turned on. Shadow test runs send nothing.
Honest limits
- The widget binds to your page through the browser: CSP
frame-ancestors, and at the exchange the framing origin the widget reports checked against the browser's own headers — a request whoseOriginis neither Minctrl nor the claimed page, or whoseSec-Fetch-Sitesays it came from another site that is not the claimed page, is refused (403) and the token stays unused. These are browser-side controls: a script outside a browser that holds a valid token sends no such headers and can still exchange it until it is used or expires — which is why tokens live at most 15 minutes, are used once, and can only ever sign as their member (who allowed embedded signing). - Custom email addresses are not offered: the From address stays the server's.
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.
Audit export, SIEM sinks and evidence
Stream the hash-linked audit chain to Splunk, Datadog or a signed webhook without ever skipping an entry, export any range with its hashes and a verification manifest, hand an auditor an evidence pack, and anchor the chain head with an RFC 3161 timestamp.