---
title: "Embed sessions"
description: "Mint short-lived, origin-bound browser credentials for the embedded Designer and event control room."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.seatlayer.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

| Token | Surface | Resource scope | Authorization scope |
|---|---|---|---|
| `dse_…` | Embedded Designer | One workspace and chart | `read-only`, `edit`, or `publish` |
| `mse_…` | SeatManager control room | One event | Explicit event capabilities |

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

```text title="browser-trust-boundary.txt"
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

**POST /v1/designer/sessions** — Authentication: Secret key

```bash
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

| Authority | Read | Save draft | Publish |
|---|---:|---:|---:|
| `read-only` | Yes | No | No |
| `edit` | Yes | Yes | No |
| `publish` | Yes | Yes | Yes |

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:

```json
{
  "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.

**DELETE /v1/designer/sessions/:id** — Authentication: Secret key

## Manage session

**POST /v1/events/:key/manage-sessions** — Authentication: Secret key or authorized dashboard session

```bash
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
  }'
```

| Capability | Allows |
|---|---|
| `event:view` | Live board, section rules, and checkout-window reads |
| `event:block` | Block/unblock, section availability, and hold-TTL writes |
| `event:cancel` | Booking-reference-guarded cancellation |
| `event:reports` | Report, CSV, audit log, and revenue projection |

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

**DELETE /v1/events/:key/manage-sessions/:id** — Authentication: Secret key

## 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](/platform/embedded-designer) or
[embedded control room](/platform/embedded-control-room).

Source: https://docs.seatlayer.io/platform/embed-sessions/index.mdx