Session API Overview
Mint, refresh, list, and revoke embed sessions for workspace-scoped access.
Meshes embed sessions are created from the private management API and are always scoped to a single workspace.
Endpoints
POST /api/v1/sessionsPOST /api/v1/sessions/:sessionId/refreshGET /api/v1/sessionsDELETE /api/v1/sessions/:sessionId
Mint a session
POST /api/v1/sessions accepts:
workspace_id(required UUID)role(member,admin,owner; defaultmember)external_user_id(optional string)ttl_seconds(optional,300-3600, default1800)launch_ttl_seconds(optional,15-60, default30)launch_path(optional, must start with/workspace/, default/workspace/dashboard)allowed_origins(optional array of up to 10 origin URLs; recommended for production)scopes(optional array; current public scope isevents.payload:read)
Typical fields most integrations use:
{
"session_id": "sess_550e8400-e29b-41d4-a716-446655440000",
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"expires_at": "2026-03-15T12:00:00Z",
"launch_url": "https://embed.meshes.io/workspace/dashboard?launch=...",
"workspace_id": "550e8400-e29b-41d4-a716-446655440000",
"role": "admin"
}
Use launch_url directly in your iframe. Most integrations do not need to inspect any bootstrap token value separately.
Refresh a session
POST /api/v1/sessions/:sessionId/refresh returns a new access_token for the same logical session.
Important behavior:
- the
session_idstays the same - the response returns a new
access_token - it does not return a new
launch_url
Use refresh for already-mounted iframes. Use minting again when you need a new full bootstrap flow.
List sessions
GET /api/v1/sessions requires workspace_id and supports the same cursor pagination shape used by other Meshes list endpoints.
Query params:
workspace_id(required UUID)status(optional:activeorrevoked)cursor(optional)limit(optional)
Revoke a session
DELETE /api/v1/sessions/:sessionId revokes the logical session. After revocation, later session-authenticated API requests fail.