Docs / FAQ
Back to docs

FAQ

Answers to common questions about tokens, embeds, widget mode, public runs, and BYOK.

Most common Security
If you only remember one rule: never put tokens in URLs.
Embed token (mtok_…) goes to:
  • HTTP header: x-microapp-embed-token
  • postMessage: host → iframe/widget after READY
What is an embed token (mtok_…)?
Embed tokens are used to run tools from customer-facing embeds (iframe/widget) and from embed-mode API calls.
  • Send mtok_… via HTTP header x-microapp-embed-token.
  • Never put mtok_… in a URL (query params).
  • Rotate/revoke tokens if leaked.
What is an owner key (mk_…)?
Owner keys are for management actions only: creating/revoking tokens, changing settings like public runs, etc.
  • Never use mk_… in embeds.
  • Store mk_… privately (local storage is ok for your own dashboard).
  • If mk_… leaks, rotate immediately.
Why are tokens not allowed in URLs?
URLs leak easily: browser history, server logs, analytics, referrer headers, screenshots, and support tickets.
  • Use headers for API calls.
  • Use postMessage for iframe/widget auth.
  • Never rely on query-string tokens.
How do iframe embeds authenticate?
The iframe loads with a clean URL (no token). After the iframe signals READY, the host sends MICROAPP_EMBED_INIT via postMessage containing the token + optional config.
  • Always validate ev.origin in your host listener.
  • Token is sent only after READY.
  • Use strict origin rules for your embed host.
How does the widget authenticate?
The widget SDK loads an iframe and performs an auth handshake via postMessage internally. The token is never placed in the iframe URL.
  • You pass mtok to MicroappWidget.mount.
  • SDK sends token via postMessage after iframe READY.
  • No query tokens.
What is embed mode (embed=1)?
Embed mode is the server-side mode for customer-facing requests. Endpoints accept mtok via header and apply embed rules, quotas and rate limits.
  • Call /api/tools/:slug/schema?embed=1 with x-microapp-embed-token.
  • Call /api/tools/:slug/run?embed=1 with x-microapp-embed-token.
  • Authorization Bearer under embed=1 is not a fallback path.
Can I pass the embed token in the URL query string?
No. Query-string tokens are not accepted.
  • If you see any examples that put the token in the URL, treat them as outdated/invalid.
What are Public runs?
Public runs allow anyone to run the tool without a token. This is controlled by the owner.
  • Public runs consume the owner’s quotas.
  • Embed tokens still work even if public runs are disabled.
  • LLM tools remain BYOK-gated.
What is BYOK and when is it required?
BYOK (Bring Your Own Key) means the tool owner must add an AI provider key for LLM-powered tools. Runtime AI is not provided by the platform.
  • If the tool requires AI and the owner has no active AI key, runs return byok_required.
  • byok_required is side-effect-free (no run logs, no quota usage).
What happens if the LLM provider fails?
The run returns llm_error. The failure is logged, embed token last_used_at is touched, and quotas are refunded (no net usage increase).
Do you have rate limits?
Yes. There is a short-window rate limit per tool to prevent abuse, plus daily quota windows that reset at 00:00 UTC.
How do I debug a 401 error?
Most 401s come from sending the token via the wrong channel or mixing auth types.
  • For embed API calls: use embed=1 + x-microapp-embed-token header.
  • Do not pass mtok in query params.
  • Do not send Authorization Bearer in embed mode unless it is an embed token (avoid mixing).
  • If you rotated/revoked a token, create a new one.
Is my token stored in plaintext on the server?
No. Tokens are stored hash-only. The raw token is shown only once at creation time.