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

# Embed the assistant

> Put the WPOS agent inside your own product as a branded iframe, for both your operators and your end customers, without exposing your API key.

The embedded assistant is the WPOS agent running inside your product, in an
iframe, branded as yours. Your operators drive it as a `manager`, and your end
customers drive it as a `client`. The browser never holds your API key: you mint a
short-lived, site-scoped session token on your server and load it in the frame.
This needs the `embed` scope.

## How it fits together

<Steps>
  <Step title="Mint a session on your server">
    Call `POST /sites/:siteId/embed-session` with your partner key. You get a
    one-hour token and a ready-to-frame URL. The site must belong to you.

    ```bash theme={null}
    curl -X POST https://api.wpcursor.com/api/partner/v1/sites/site_.../embed-session \
      -H "X-Partner-Key: $WPOS_PARTNER_KEY" \
      -H "Content-Type: application/json" \
      -d '{ "role": "client", "displayName": "Jordan" }'
    ```

    ```json theme={null}
    {
      "success": true,
      "role": "client",
      "token": "...",
      "expiresIn": 3600,
      "url": "https://api.wpcursor.com/embed/chat?token=..."
    }
    ```
  </Step>

  <Step title="Frame the URL">
    Drop the returned `url` into an iframe in your app.

    ```html theme={null}
    <iframe
      src="https://api.wpcursor.com/embed/chat?token=..."
      style="width:100%;height:600px;border:0"
      title="Website Assistant">
    </iframe>
    ```

    The embed surface sets a `frame-ancestors` policy that allows your configured
    origins, so it loads inside your app and nowhere else.
  </Step>

  <Step title="Your customer chats">
    The assistant loads with your branding and runs the agent on the token's site.
    Each message is a build job under the hood, bounded by the same credits and
    caps as the [Build jobs](/partners/build-jobs) API. When the token expires
    after an hour, mint another.
  </Step>
</Steps>

## Roles

| Role      | For                | Framing                                              |
| --------- | ------------------ | ---------------------------------------------------- |
| `manager` | Your operators     | Full agent access, presented as an operator tool.    |
| `client`  | Your end customers | The same execution, presented as "request a change". |

The role is stamped into the session token and travels with every job the session
runs, so your reporting can tell operator work from customer work.

## Branding

The embedded assistant renders with the site's white-label branding: agency name,
logo, and accent color, falling back to your partner defaults. Set them per site
through [Branding](/partners/branding), or set partner-wide defaults with WPOS. No
WPOS name appears to your customer.

## Security model

<Warning>
  Mint session tokens on your server, never in the browser, and never ship your
  partner key to the client. The embed token is deliberately narrow: it is
  site-scoped, expires in an hour, and only works on the embed surface. It cannot
  read your other sites or your account.
</Warning>

* The token is an embed-only credential. It cannot be used as a partner key or a
  site token.
* Everything the frame can do is scoped to the one site the token was minted for.
* Configure which origins may frame the assistant with WPOS when you set up your
  embed integration.

## Next

<CardGroup cols={2}>
  <Card title="Branding" icon="paintbrush" href="/partners/branding">
    Set the name, logo, and color your customers see.
  </Card>

  <Card title="Build jobs" icon="robot" href="/partners/build-jobs">
    The API the embedded assistant runs on.
  </Card>
</CardGroup>