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

# Iframe Embedding

> Embed the whatabot flow editor in your own application.

## Overview

whatabot's flow editor can be embedded directly into your own application using an **iframe**. This allows you to offer flow-building capabilities to your users without them needing to leave your platform.

## Requirements

To embed the flow editor, you need:

1. **An OAuth client** -- created in your workspace settings, providing a `clientId` and `clientSecret`.
2. **A workspace with `iframe_enabled` set to `true`** -- iframe embedding must be explicitly enabled on the workspace.
3. **A backend service** -- your server handles the authentication handshake so the client secret is never exposed to the browser.

<Callout type="warning">
  The `clientSecret` must never be exposed in frontend code. All authentication
  with the client secret must happen on your backend. See [Embed
  Authentication](/en/embed/authentication) for the secure flow.
</Callout>

## How it works

The iframe uses a combination of **client credentials** and **one-time token (OTT)** authentication:

1. Your backend authenticates with whatabot using the client credentials (Basic Auth).
2. whatabot returns a one-time token (OTT) valid for 60 seconds.
3. Your frontend passes the OTT to the iframe, which exchanges it for access and refresh tokens.
4. The iframe uses those tokens to interact with the whatabot API.

## Iframe URL

The iframe URL follows this format:

```
https://flow.whatabot.app/{language}/flows/builder/{flowId}
```

| Parameter    | Description                                             |
| ------------ | ------------------------------------------------------- |
| `{language}` | Interface language: `en` (English) or `pt` (Portuguese) |
| `{flowId}`   | UUID of the flow to edit                                |

Example:

```
https://flow.whatabot.app/en/flows/builder/019cfebf-b789-794b-9a86-3098d6e82772
```

<Warning>
  The iframe can only open URLs in the format above. Any other path will be blocked.
</Warning>

### Theme

You can customize the editor theme by adding the `theme` query param:

```
https://flow.whatabot.app/en/flows/builder/{flowId}?theme=dark
```

| Value   | Description           |
| ------- | --------------------- |
| `light` | Light theme (default) |
| `dark`  | Dark theme            |

## Client token scope

Client tokens are **scoped to a single workspace**. An embedded editor can only access resources within the workspace the OAuth client was created for.

## Use case

Imagine you have a SaaS platform and want to allow your customers to create and edit conversation flows directly within your system.

1. **List the flows** from the workspace using the [List Flows](/en/api-reference/flows/list-flows) endpoint with your API key:

```bash theme={null}
curl -X GET "https://api.whatabot.app/api/v1/flows" \
  -H "X-Api-Key: wh_your_api_key"
```

2. **Display the flows** in your UI for the user to choose which one to edit.

3. **Open the embedded editor** with the selected `flowId`:

```
https://flow.whatabot.app/en/flows/builder/{flowId}?theme=light
```

This way, your user can list, select, and edit flows without leaving your platform.

## Next steps

<CardGroup cols={1}>
  <Card title="Embed Authentication" icon="lock" href="/en/embed/authentication">
    Learn the full 3-step authentication flow for the embedded editor, including
    code examples.
  </Card>
</CardGroup>