Docs / Quickstart

Quickstart

Create a tool → go live → generate an embed token → embed via iframe or widget.

1) Replace these placeholders

  • baseHost: your Microapp host (https://microapp.microapp-esat.workers.dev)
  • slug: your tool slug (from URL: /tools/<slug>/…)
  • token: your embed token (mtok_…) created in the tool’s “Embed tokens” page
  • FIELD_KEY: copy from schema response: schema.normalizedFields[].key
Security rule: Never put mtok_… in the URL. Use headers (API) or postMessage (iframe/widget). Never use mk_… in embeds.

2) What you need

  • A LIVE tool (a slug like my-tool).
  • An embed token (mtok_…).
  • If the tool requires LLM: the tool owner must configure BYOK (owner AI key). Otherwise you may get byok_required.

3) Embed with iframe + postMessage

The iframe URL contains only the tool slug. After the iframe signals READY, you send the token via postMessage.

Iframe HTML
<iframe
  id="microapp"
  src="https://YOUR_MICROAPP_HOST/embed/tools/YOUR_SLUG"
  style="width:100%;height:720px;border:0;border-radius:16px;overflow:hidden"
  loading="lazy"
  title="Microapp embed"
></iframe>
Host script
// Host-side integration (recommended)
// - iframe URL has NO token
// - token is sent via postMessage after iframe says READY
// Tip: For extra security, validate ev.origin matches your Microapp host origin.

const iframe = document.getElementById("microapp");
let inited = false;

window.addEventListener("message", (ev) => {
  if (!iframe || ev.source !== iframe.contentWindow) return;

  const data = ev.data || {};
  if (data.type === "MICROAPP_EMBED_READY") {
    if (inited) return;
    inited = true;

    iframe.contentWindow.postMessage(
      {
        type: "MICROAPP_EMBED_INIT",
        slug: "YOUR_SLUG",
        token: "mtok_YOUR_TOKEN",
        config: { locale: "en-US", currency: "USD", timeZone: "Europe/Istanbul" }
      },
      ev.origin
    );
  }
});

4) Embed with Widget (SDK mount)

Widget is a drop-in embed option beyond iframe. It still never places the token in URL; token is sent via postMessage internally.

<!-- Microapp Widget (SDK mount) -->
<!-- Token is NEVER in the iframe URL; SDK sends it via postMessage -->
<script src="https://YOUR_MICROAPP_HOST/microapp-widget.js"></script>

<script>
(function(){
  function boot(){
    if (!window.MicroappWidget) return setTimeout(boot, 50);

    window.MicroappWidget.mount({
      baseUrl: "https://YOUR_MICROAPP_HOST",
      toolSlug: "YOUR_SLUG",
      mtok: "mtok_YOUR_TOKEN",

      mode: "floating",
      anchor: "bottom-right",
      offsetX: 16,
      offsetY: 16,

      autoOpen: true,
      debug: false
    });
  }
  boot();
})();
</script>
If you paste a real token into the snippet, treat it as a secret.

5) Call the API (schema/run)

For embeds, always use embed=1 and pass token via header x-microapp-embed-token.

cURL: schema
curl -s "https://YOUR_MICROAPP_HOST/api/tools/YOUR_SLUG/schema?embed=1" \
  -H "accept: application/json" \
  -H "x-microapp-embed-token: mtok_YOUR_TOKEN"
cURL: run
curl -s "https://YOUR_MICROAPP_HOST/api/tools/YOUR_SLUG/run?embed=1" \
  -H "accept: application/json" \
  -H "content-type: application/json" \
  -H "x-microapp-embed-token: mtok_YOUR_TOKEN" \
  --data '{"input":{"FIELD_KEY":"hello"}}'
Windows PowerShell (curl.exe)
# Windows PowerShell (curl.exe) — pipe JSON via stdin (reliable)
$BASE = "https://YOUR_MICROAPP_HOST"
$SLUG = "YOUR_SLUG"
$MTOK = "mtok_YOUR_TOKEN"

'{"input":{"FIELD_KEY":"hello"}}' | curl.exe -sS -i -X POST "$BASE/api/tools/$SLUG/run?embed=1" `
  -H "content-type: application/json" `
  -H "accept: application/json" `
  -H "x-microapp-embed-token: $MTOK" `
  --data-binary '@-'

6) Health / version check

Before debugging tokens, confirm the platform is up and you are running the build you expect.

cURL: health
curl -s "https://YOUR_MICROAPP_HOST/api/health"
cURL: version
curl -s "https://YOUR_MICROAPP_HOST/api/version"
Windows PowerShell
# Windows PowerShell (recommended)
$BASE = "https://YOUR_MICROAPP_HOST"

Invoke-RestMethod "$BASE/api/health"  | ConvertTo-Json -Depth 8
Invoke-RestMethod "$BASE/api/version" | ConvertTo-Json -Depth 8
Tip: If /api/health is 200 but embeds fail, it’s almost always token transport (header/postMessage) or origin/CSP rules — not uptime.

Troubleshooting

  • invalid_token: token revoked/invalid or not sent via header/postMessage.
  • missing_auth: calling embed endpoints without mtok header (or not using postMessage init).
  • byok_required: tool needs LLM but owner AI key is missing/inactive.
  • quota_exceeded: plan limit reached (runs / ai actions).
  • Nothing shows in iframe: check browser console for CSP/frame-ancestors or postMessage origin issues.
  • API calls fail: confirm embed=1 and header x-microapp-embed-token (no query token).