> For the complete documentation index, see [llms.txt](https://docs.scaleflex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleflex.com/developers-headless/studio/template-builder/embedding-and-origins.md).

# Embedding and origins

Two things have to be true before an embedded editor can authenticate: your origin must be allowed to frame the deployment, and the browser must accept the deployment's cookies from inside that frame. Both fail quietly, so both are worth setting up deliberately.

### Origin registration

Your page's origin must be in the deployment's embedding allowlist, held in `NEXT_PUBLIC_TRUSTED_HUB_ORIGINS`. Without it the browser refuses to load the editor: Chrome shows "refused to connect" where the frame should be, and the widget reports `handshake-timeout`.

A deployment allows these out of the box:

* `'self'`
* `https://*.scaleflex.com`
* `https://*.filerobot.com`
* `http://localhost:5173`

plus whatever its own `NEXT_PUBLIC_TRUSTED_HUB_ORIGINS` names.

{% hint style="warning" %}
**The list is baked in at build time.** Adding your domain takes a rebuild of the deployment, not just a restart.
{% endhint %}

The check runs in both directions. The widget only accepts messages from the `base-url` origin, and the deployment only accepts a template from the origin pinned when the credential was handed over.

### How the credential reaches the editor

The widget loads the editor with the credential in the URL query string. The deployment strips those parameters immediately, redirects to a clean URL, and keeps the values in cookies for the rest of the session:

| Parameter     | Carries                                                     |
| ------------- | ----------------------------------------------------------- |
| `ftoken`      | The Scaleflex project token                                 |
| `sassKey`     | The project sass key, with a Hub session                    |
| `suuid`       | The Hub session uuid                                        |
| `cuuid`       | Company uuid, session mode only                             |
| `puuid`       | Project uuid, session mode only                             |
| `secTemplate` | The security-template key, instead of `sassKey` and `suuid` |
| `iframe`      | Marks the session as embedded                               |
| `embedOrigin` | The origin to target with postMessage replies               |
| `brandColor`  | Accent color for the editor chrome                          |
| `theme`       | `light`, `dark` or `auto`                                   |

You do not normally construct that URL yourself - the widget does it from the attributes. It matters when you are diagnosing an embed, because it explains why the editor's URL looks clean while the session persists.

Three of those values are validated at the boundary rather than trusted:

* **`embedOrigin`** must parse as a URL, and only its origin is kept, because it becomes a `postMessage` target.
* **`brandColor`** must be `#rgb` or `#rrggbb`. The value ends up inside a stylesheet rule, so the shape is enforced rather than escaped.
* **`theme`** must be one of the three names.

Anything that fails is dropped, and the editor keeps its default.

`embedOrigin` also has a rule worth knowing: it can only be pinned or repinned **together with fresh credentials**. A bare link carrying only `embedOrigin` cannot retarget an existing session's messages. Symmetrically, a credential handoff that names no origin unpins whatever the last embedder pinned, so a browser that used the widget and later opens a different embed of the same deployment does not keep messaging the old origin.

### Cookies

The deployment stores auth in **partitioned cookies (CHIPS)**, scoped to your site. Over HTTPS they are written `Secure; SameSite=None; Partitioned`, which is what lets them survive third-party framing in browsers that block unpartitioned third-party cookies.

`SameSite=None` requires `Secure`, which requires HTTPS. Over plain HTTP the deployment falls back to `SameSite=Lax`, which is fine for same-site development and will not work cross-site.

As [Authentication](https://docs.scaleflex.com/developers-headless/studio/template-builder/authentication.md) notes, these cookies are readable by JavaScript on the deployment origin, because the client attaches them to Filerobot as request headers.

{% hint style="warning" %}
**A browser without CHIPS support that blocks third-party cookies cannot authenticate an embedded editor.** It fails with `auth` or `handshake-timeout`, and there is no workaround from your side. Same-site embeds are unaffected.
{% endhint %}

### Browser support

| Browser         | Minimum version |
| --------------- | --------------- |
| Chrome          | 114             |
| Firefox         | 131             |
| Safari          | 18.4            |
| Edge (Chromium) | 114             |

Requires native Custom Elements v1, Shadow DOM and ES2020. Internet Explorer is not supported.

These floors are higher than a plain web component would need, and partitioned cookies are the reason. A same-site embed works further back.

### Where to go next

* [Authentication](https://docs.scaleflex.com/developers-headless/studio/template-builder/authentication.md) - which credential, and how to scope it
* [Troubleshooting](https://docs.scaleflex.com/developers-headless/studio/template-builder/troubleshooting.md) - what each failure looks like
