Session API Overview

Meshes embed sessions are created from the private management API and always target a single workspace. You can now choose a session_type to expose the full workspace embed surface, one locked resource scope, or a read-only dashboard view.

Endpoints

• POST /api/v1/sessions
• POST /api/v1/sessions/:sessionId/refresh
• GET /api/v1/sessions
• DELETE /api/v1/sessions/:sessionId

Mint a session

POST /api/v1/sessions accepts:

• workspace_id (required UUID)
• role (member, admin, owner; default member)
• session_type (workspace, resource, dashboard; default workspace)
• external_user_id (optional string)
• ttl_seconds (optional, 300-3600, default 1800)
• launch_ttl_seconds (optional, 15-60, default 30)
• launch_page (dashboard, connections, rules, events; default dashboard)
• resource (required for resource sessions only)
• resource_id (required for resource sessions only)
• allowed_origins (optional array of up to 10 origin URLs; recommended for production)
• scopes (optional array; current public scope is events.payload:read)

Important rules:

• launch_page chooses only the initial top-level page. It is not a freeform route string.
• resource sessions must include both resource and resource_id.
• resource sessions can launch into dashboard, rules, or events.
• dashboard sessions are read-only, dashboard-only, and must use launch_page: 'dashboard'.

Workspace session example

{
  "session_type": "workspace",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "role": "admin",
  "ttl_seconds": 1800,
  "launch_page": "dashboard",
  "allowed_origins": ["https://app.example.com"]
}

Resource session example

{
  "session_type": "resource",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "role": "admin",
  "launch_page": "rules",
  "resource": "account",
  "resource_id": "acct_123",
  "allowed_origins": ["https://app.example.com"]
}

Dashboard session example

{
  "session_type": "dashboard",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "role": "member",
  "launch_page": "dashboard",
  "allowed_origins": ["https://app.example.com"]
}

Typical response fields:

{
  "session_id": "sess_550e8400-e29b-41d4-a716-446655440000",
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2026-03-22T12:00:00Z",
  "launch_url": "https://embed.meshes.io/workspace/rules?launch=...",
  "workspace_id": "550e8400-e29b-41d4-a716-446655440000",
  "role": "admin",
  "session_type": "resource",
  "resource": "account",
  "resource_id": "acct_123"
}

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_id stays the same
• the response returns a new access_token
• the response preserves session_type, resource, and resource_id
• 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: active or revoked)
• cursor (optional)
• limit (optional)

List responses also include additive session fields such as session_type, resource, and resource_id.

Revoke a session

DELETE /api/v1/sessions/:sessionId revokes the logical session. After revocation, later session-authenticated API requests fail.

Related docs

• Launch URL and Iframe Bootstrap
• Session Refresh Lifecycle
• Session Roles and Scopes