Preview tokens (mp_*) are short-lived signed credentials that allow you to embed a running sandbox in an <iframe> from a third-party frontend without exposing your msk_* API key to the browser.
Base path: /api/v1/sandboxes/{id}/preview-token
Endpoints
| Method | Path | Description |
|---|---|---|
POST | /api/v1/sandboxes/{id}/preview-token | Mint a preview token |
Mint a Preview Token
POST /api/v1/sandboxes/{id}/preview-token
Generates a signed preview token tied to the sandbox. The returned url is ready to use as an iframe src.
Auth
Requires an API key or JWT with the previews:write scope.
Authorization: Bearer msk_...Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
expires_in | integer | No | 3600 | Token TTL in seconds (max 86400) |
scope | string | No | "read" | "read" or "interact" |
{
"expires_in": 3600,
"scope": "read"
}Response - 200 OK
{
"token": "mp_eyJhbGciOiJIUzI1NiJ9...",
"url": "https://sbx-abc123.sandboxes.miosa.ai?mt=mp_eyJ...",
"expires_at": "2026-05-26T04:00:00Z",
"scope": "read"
}| Field | Type | Description |
|---|---|---|
token | string | Signed preview token (mp_<base64url>) |
url | string | Iframe-ready URL with token pre-embedded as ?mt= query param |
expires_at | string | ISO 8601 expiry timestamp |
scope | string | "read" or "interact" |
Scopes
| Scope | Description |
|---|---|
read | View-only. Mouse and keyboard input are blocked. |
interact | Full mouse/keyboard input forwarded into the sandbox. |
Errors
| Status | Code | Cause |
|---|---|---|
| 404 | sandbox_not_found | Sandbox does not exist or belongs to a different tenant |
| 403 | forbidden | Tenant mismatch |
| 422 | invalid_scope | scope is not "read" or "interact" |
Examples
Token Format
Preview tokens use the prefix mp_ followed by a base64url-encoded signed payload. The token is consumed by the sandbox proxy when passed as the ?mt= query parameter. Do not parse the token body - treat it as opaque.
Iframe Embedding
<!-- Read-only embed - no API key in the browser -->
<iframe
src="https://sbx-abc123.sandboxes.miosa.ai?mt=mp_eyJ..."
width="1280"
height="800"
allow="clipboard-read; clipboard-write"
></iframe>The token is verified by the sandbox proxy on every request during the token’s lifetime. Once it expires, the iframe will show an access-denied page.