# Mint a builder session for a browser

`POST /v1/embed-sessions`

Requires an API key with the `workspaces:manage` scope. [About keys and scopes](/docs/api/authentication)

Partner keys only, from your server, with `Kirora-Workspace` naming the tenant. Returns a token the embedded segment and email builders send as `Authorization: Bearer es_…` for 15 minutes; the SDK asks your server for a new one before it expires. The key must have `allowedOrigins`, and a session is refused with 403 `EMBED_ORIGIN_NOT_ALLOWED` from any other origin. A session reads what its `components` need, renders previews, counts audiences and uploads images; it never creates, edits, deletes, publishes or sends, since your server saves what the builders return. It sees masked attributes as a member does, and attribute values and event property samples only with `includeAttributeValues`. Revoking the key ends every session it minted.

## Request body

- `components` (string[], required, at least 1 item) — The builders the browser may load; each opens only the routes it needs.
- `includeAttributeValues` (boolean, optional, default `false`) — Lets the session read attribute values and event property samples, for value suggestions. Off by default: they are the workspace's customer data.

## Returns

Returns `201 Created` with a `EmbedSession` in `data`. Otherwise returns an error; [Errors](/docs/api/errors) lists every code and which to retry.

- `token` (string, required) — For Kirora's hosted builder, which sends it as `Authorization: Bearer <token>`; it works only inside a page whose origin the partner key allows.
- `expiresAt` (string, required, date-time) — When the token stops working (15 minutes).
- `apiUrl` (string, required, uri) — The API's base URL, for `KiroraProvider`'s `apiUrl`.
- `builderUrl` (string, required, uri) — The hosted builders' base address; `@kirora/react` opens each builder under it.

## Example

```bash
curl -X POST https://api.kirora.io/v1/embed-sessions \
  -H "Authorization: Bearer $KIRORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "components": [
      "segment-builder"
    ]
  }'
```

Response `201`:

```json
{
  "data": {
    "token": "token_example",
    "expiresAt": "2030-03-14T09:30:00Z",
    "apiUrl": "https://example.com",
    "builderUrl": "https://example.com"
  }
}
```