Preview tokens

A preview token (mp_...) is a short-lived credential that grants read-only access to a specific sandbox preview. You mint it server-side and pass it to the browser. The browser uses it as the src of an <iframe>. Your msk_* API key never leaves your server.

Why preview tokens exist

Sandbox previews are live HTTP services running inside isolated VMs. To embed one in your product UI, the browser needs to make an authenticated request to the MIOSA preview proxy.

The wrong approach - passing your API key to the browser - would let any user call the MIOSA API as your account. Preview tokens are the correct boundary: scoped to one sandbox, one port, and a short TTL.

Token format

Preview tokens are opaque strings prefixed mp_ followed by a base64url-encoded payload:

mp_<base64url-encoded-payload>

Do not parse or validate the payload in your application code. Treat the token as an opaque string. MIOSA verifies it at the proxy edge on every request.

TTL strategy

When a token expires, the iframe shows a “session expired” message from the preview proxy. Your UI should catch the message event from the iframe and re-mint a token transparently.

Server-side mint flow

Iframe attachment

Once you have the embed_url, set it as the src of an <iframe>:

<iframe
  src="https://preview.opendesigns.ai/p/sbx_abc123?token=mp_..."
  allow="clipboard-read; clipboard-write"
  sandbox="allow-scripts allow-same-origin allow-forms allow-popups"
  style="width: 100%; height: 600px; border: none;"
  title="Design workspace"
></iframe>

sandbox attribute guidance:

Do not add allow-top-navigation - it would let sandbox content redirect your top-level page.

Token refresh

Detect expiry by listening for the message event from the iframe:

window.addEventListener("message", async (event) => {
  // The preview proxy emits this message when the token expires.
  if (event.data?.type === "miosa:preview:expired") {
    const res = await fetch(`/api/embed-url?sandbox_id=${sandboxId}`);
    const { embed_url } = await res.json();
    document.getElementById("sandbox-frame").src = embed_url;
  }
});

Permission scoping

When you mint a token for an end user, scope it to the minimum permissions they need:

Available permission scopes:

Early revocation

Revoke a preview token before it expires - for example, when a user logs out or loses access:

See also

• End-to-end white-label walkthrough
• Webhooks reference
• Browser Tokens