> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yo-lead.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a session

> Create an iframe session with the Public API.

Use `POST /v1/embed/sessions` to create an iframe session.

The request must be signed with the same HMAC headers as other Public API requests.

<Warning>
  Create embed sessions on your backend. Do not call this endpoint from browser code because it requires the API secret.
</Warning>

```json theme={null}
{
  "employeeId": "64f000000000000000000001",
  "chatId": "64f000000000000000000002",
  "capabilities": ["showChatPage"]
}
```

Request fields:

| Field          | Type     | Required | Description                                                                                                        |
| -------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `employeeId`   | `string` | Yes      | Active YoLead employee id that will act inside the iframe.                                                         |
| `chatId`       | `string` | No       | Chat to open or restrict the iframe session to. Required when `showChatPage` is requested without `showChatsList`. |
| `capabilities` | `array`  | Yes      | List of requested iframe capabilities. At least one view capability must remain after scope filtering.             |

The response contains `iframeUrl`. Render that URL in an iframe on your frontend.

```json theme={null}
{
  "data": {
    "iframeUrl": "https://app.yo-lead.com/embed/chats/64f000000000000000000002#token=eyJ...",
    "embedToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresAt": "2026-05-08T12:15:00.000Z",
    "capabilities": ["showChatPage"],
    "allowedChatId": "64f000000000000000000002"
  }
}
```

```html theme={null}
<iframe src="https://app.yo-lead.com/embed/chats/64f000000000000000000002#token=..." />
```

Response fields:

| Field           | Type     | Description                                                                                    |
| --------------- | -------- | ---------------------------------------------------------------------------------------------- |
| `iframeUrl`     | `string` | URL to render in the customer frontend.                                                        |
| `embedToken`    | `string` | Short-lived token consumed by the YoLead iframe runtime.                                       |
| `expiresAt`     | `string` | Token expiration time as an ISO 8601 date-time string. Embed sessions expire after 60 minutes. |
| `capabilities`  | `array`  | Effective capabilities granted to this session after API key scope filtering.                  |
| `allowedChatId` | `string` | Present when the session is restricted to a single chat.                                       |

## Validation rules

* `employeeId` must belong to an active employee in the API key company.
* Requested capabilities are filtered by API key scope.
* `read` keys can only grant `showChatsList` and `showChatPage`.
* `read-write` keys can grant all supported capabilities.
* At least one view capability is required: `showChatsList` or `showChatPage`.
* If `showChatPage` is requested without `showChatsList`, `chatId` is required.
* If `chatId` is provided, the employee must have access to that chat.