Minctrl Docs
Guides

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

piecewherewho
Allowed originsSettings → Embeddingchanged with settings.governance (owner, admin); read with it or api_keys.manage
Embedded signingSettings → Embeddingeach member for themself; the company's allow-list with settings.governance
Embed keys (embed:issue)Settings → Embedding or API keysapi_keys.manage
Embed tokensPOST /embed/tokens from your backendan embed:issue key
Widgets/embed/signoff, /embed/run/<id> in your iframethe SDK @minctrl/embed
BrandingSettings → Brandingcompany.update
Host webhooksSettings → Webhooksnotifications.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. With embed.sign they 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 holding settings.governance puts 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) — and embed.sign also needs gate.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 in process; set all_processes: true to cover every process's gates — 422 otherwise) or run with run_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:

eventdata
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 (and gate.approve.high_tier for 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:

fieldrule
Display name1–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 emailshown as “Questions? …”.
Email sender namea name only — emails always come from the server's own address, so SPF and DKIM keep holding.
LogoPNG, 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.com shows 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_failing in 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.test without 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 whose Origin is neither Minctrl nor the claimed page, or whose Sec-Fetch-Site says 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.

On this page