Quickstart
Embed a Meshes workspace in your app using a launch URL and a session token.
This quickstart shows the minimum integration path for embedding Meshes inside your application.
1. Mint a session on your backend
Call POST /api/v1/sessions from your backend with your Meshes management credentials.
{
"workspace_id": "550e8400-e29b-41d4-a716-446655440000",
"role": "admin",
"ttl_seconds": 1800,
"launch_ttl_seconds": 30,
"launch_path": "/workspace/dashboard",
"allowed_origins": ["https://app.example.com"]
}
The response includes:
access_tokensession_idlaunch_urlexpires_at
2. Set the iframe source
Use the returned launch_url as the iframe source.
<iframe
src={launchUrl}
title="Meshes workspace"
style={{ width: '100%', border: 0 }}
/>
3. Add one host-side message handler
Use the launch_url to derive the expected embed origin, then ignore messages from any other origin.
const iframe = document.querySelector('iframe');
const embedOrigin = new URL(launchUrl).origin;
window.addEventListener('message', async (event) => {
if (event.origin !== embedOrigin) return;
if (event.source !== iframe?.contentWindow) return;
switch (event.data?.type) {
case 'meshes:ready':
iframe?.contentWindow?.postMessage(
{
type: 'meshes:auth',
token: accessToken,
},
embedOrigin
);
break;
case 'meshes:token-refresh': {
const refreshed = await refreshMeshesSession(sessionId);
accessToken = refreshed.access_token;
iframe?.contentWindow?.postMessage(
{
type: 'meshes:auth',
token: accessToken,
},
embedOrigin
);
break;
}
case 'meshes:resize':
iframe.style.height = `${Math.max(480, event.data.height)}px`;
break;
}
});
4. Let meshes:ready start the runtime session
When the iframe sends meshes:ready, send the current access_token with meshes:auth.
This is the runtime credential. The launch URL is only for the initial iframe request.
5. Refresh in place when the iframe asks
When the iframe later sends meshes:token-refresh, call POST /api/v1/sessions/:sessionId/refresh on your backend and send the new access_token back with another meshes:auth.
6. Hard reload behavior
If the iframe is fully reloaded, mint a fresh session or at least a fresh launch_url before mounting it again.
End-to-end flow summary
- your backend mints a session
- your frontend mounts the iframe with
launch_url - the iframe sends
meshes:ready - your frontend sends
meshes:auth - the iframe sends
meshes:token-refreshwhen it needs a new token - your frontend refreshes the session on your backend and sends the new token