Embed sessions

Never expose an sk_… secret key to a browser. Mint a short-lived embed session for exactly the chart editor or event operator surface the signed-in user is allowed to open.

Both tokens are bound to an exact browser origin, returned only when created, stored by SeatLayer as hashes, expire automatically, and can be revoked.

Browser -> your backend: authorize current user and resource
Your backend -> SeatLayer: mint session with sk_ secret
SeatLayer -> your backend: one-time dse_ or mse_ token
Your backend -> Browser: scoped session only
Browser -> SeatLayer: scoped operations from exact allowed origin

Shared rules

• expiresInSeconds: 300–14,400; default 3,600.
• allowedOrigin: exact HTTPS origin, with no path, query, fragment, username, or password.
• Development allows http://localhost and http://127.0.0.1.
• Mint responses carry Cache-Control: no-store.
• Never log a raw token or token-bearing Designer URL.
• Revoking a session invalidates the credential without deleting the chart or changing event inventory.

Designer session

curl -sX POST "https://api.seatlayer.io/v1/designer/sessions" \
  -H "authorization: Bearer $SEATLAYER_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{
    "workspaceId": "ws_organizer_42",
    "chartId": "chart_main_hall",
    "allowedOrigin": "https://admin.example.com",
    "authority": "edit",
    "mode": "safe",
    "safeModeOptions": {
      "allowDeletingObjects": false,
      "allowEditingAreaCapacity": false
    },
    "expiresInSeconds": 3600
  }'

Designer authority

Prefer authority. Legacy canPublish remains compatible, but do not send conflicting values. When neither is supplied, the session has edit authority.

mode: "safe" restricts destructive editing for a delegated organizer. Its options can independently allow object deletion or area-capacity edits. Feature policy can further limit the public Designer feature set; treat the session response as the effective policy.

The response includes:

{
  "session": {
    "id": "dsess_1f0e",
    "token": "dse_9c1b",
    "workspaceId": "ws_organizer_42",
    "chartId": "chart_main_hall",
    "allowedOrigin": "https://admin.example.com",
    "authority": "edit",
    "canEdit": true,
    "canPublish": false,
    "mode": "safe",
    "expiresAt": 1767207600000,
    "designerUrl": "https://app.seatlayer.io/embed/designer#token=dse_9c1b"
  }
}

The token is in the URL fragment, so it is not sent as part of the iframe’s initial HTTP request.

Manage session

curl -sX POST \
  "https://api.seatlayer.io/v1/events/ev_9f3a/manage-sessions" \
  -H "authorization: Bearer $SEATLAYER_SECRET_KEY" \
  -H "content-type: application/json" \
  -d '{
    "allowedOrigin": "https://admin.example.com",
    "capabilities": ["event:view", "event:block"],
    "expiresInSeconds": 3600
  }'

Always send the smallest non-empty capability set. Omitting it grants all four for compatibility and is not recommended for a platform embed.

Rotate long-running sessions

For SeatManager, pass tokenExpiresAt and onTokenRefresh. Mint the replacement on your backend with the same event, origin, and capabilities, then return {token, expiresAt}. The SDK swaps it without rebuilding the board.

For EmbeddedDesigner, implement onRequestRelaunch, mint a fresh Designer session, and call setDesignerUrl(). Automatic renewal uses the expiry reported by the embedded app.

Backend endpoint pattern

Your own mint route must check:

1. the user is authenticated;
2. the user belongs to the host tenant;
3. the stored SeatLayer workspace/event belongs to that tenant;
4. requested authority or capabilities match the user’s role;
5. the requested origin is on your allowlist.

Return only the scoped session response. Keep SEATLAYER_SECRET_KEY in the server runtime.

Continue to embedded Designer or embedded control room.