> 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/authentication.md).

# Authentication

Two credentials get an embedded editor in. Both belong in the page from your server; neither is something to hardcode in a public bundle.

|                                                      | Hub session                           | Security template                |
| ---------------------------------------------------- | ------------------------------------- | -------------------------------- |
| Attributes                                           | `token` + `sass-key` + `session-uuid` | `token` + `sec-template`         |
| Needs a Scaleflex account per user                   | Yes                                   | **No**                           |
| Storage modes                                        | DAM-backed and stateless              | **Stateless only**               |
| Metadata fields, regional variants, project branding | Yes                                   | Empty                            |
| Rendering, fonts, asset picker                       | Yes                                   | Yes, within the template's scope |

### Security template

A **security template** is a named, permission-scoped credential you define once in your Scaleflex project. It is the same guest-auth mechanism the other Scaleflex widgets use. Hand one to the widget and no Hub session is involved at all.

This is what makes a [stateless](https://docs.scaleflex.com/developers-headless/studio/template-builder/storage-modes.md) embed work without Scaleflex accounts for your users. Even when the document never leaves your side, the editor rasterizes every text and shape layer on the server to stay pixel-identical to the CDN render, and resolves fonts and assets from your tenant - all of it authenticated. See [How rendering works](https://docs.scaleflex.com/developers-headless/studio/template-builder/how-rendering-works.md) for what those calls are.

```html
<sfx-template-builder
  base-url="https://templates.example.com"
  token="PROJECT_TOKEN"
  sec-template="SEC_TEMPLATE_KEY"
  stateless
  style="display:block;height:800px"
></sfx-template-builder>
```

```tsx
<TemplateBuilder
  stateless
  baseUrl="https://templates.example.com"
  token={projectToken}
  secTemplate={secTemplateKey}
  templateId={id}
  content={xml}
  onSave={async (data) => (await saveToYourApi(data)).ok}
/>
```

The deployment exchanges the key for a short-lived access key itself, and renews it when it expires, so the embed does not die mid-session.

#### Scoping the template

What the template cannot reach simply is not there, so scope decides what the author sees:

| Grant                         | Effect                                                                                                                                         |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `LIST` on a folder            | That folder is browsable in the asset picker                                                                                                   |
| `LIST` on `/.studio/fonts*`   | The author sees the project's custom fonts                                                                                                     |
| `UPLOAD` on `/.studio/fonts*` | The author can import fonts                                                                                                                    |
| An upload scope               | [`dam-store`](https://docs.scaleflex.com/developers-headless/studio/template-builder/storing-a-rendering-copy.md) can write its rendering copy |

**Prefer a short TTL.** The deployment re-exchanges the key when it expires, so a short-lived template costs you nothing and limits the blast radius if one leaks.

If the key is rejected - revoked, wrong project token, a typo - the widget emits `error` with code `auth`.

{% hint style="warning" %}
**Stateless only.** Setting `sec-template` without `stateless` is a configuration error: the widget reports `error` with code `invalid-config` and never mounts the editor. The dashboard and the DAM-backed editor keep requiring a session, because a leaked key would otherwise read and write other people's templates.
{% endhint %}

A security template authenticates nobody in particular - no user identity, and no project model behind it. So features that read a project model come back empty: metadata fields, regional variants and dynamic fields have nothing to read, and project branding does not apply. Theme the chrome with [`brand-color` and `theme`](https://docs.scaleflex.com/developers-headless/studio/template-builder/theming.md) instead.

### Hub session

A Hub session identifies an actual user, which is what unlocks DAM-backed storage and the project-model features a security template cannot reach. It is how the DAM's own **Edit template** action opens the builder.

```html
<sfx-template-builder
  base-url="https://templates.example.com"
  token="PROJECT_TOKEN"
  sass-key="SASS_KEY"
  session-uuid="SESSION_UUID"
  template-id="TEMPLATE_UUID"
  style="display:block;height:800px"
></sfx-template-builder>
```

`company-uuid` and `project-uuid` scope the session further and apply to this mode only.

The two modes are mutually exclusive, and the widget enforces that in both directions. A handoff in one mode clears whatever the other left behind, so a security template can never inherit a lingering sass key or project uuid, and a stale session can never outrank a credential that just arrived.

### The credential in the browser

The editor reads its own credentials from `document.cookie`, because Filerobot's API expects them as request headers rather than as cookies. They are therefore not `httpOnly`, and the deployment origin should be treated as security-sensitive.

Everything else about how those cookies are written - partitioning, the `SameSite` and `Secure` attributes, and the browser floors that follow from them - is in [Embedding and origins](https://docs.scaleflex.com/developers-headless/studio/template-builder/embedding-and-origins.md).

### Where to go next

* [Embedding and origins](https://docs.scaleflex.com/developers-headless/studio/template-builder/embedding-and-origins.md) - the allowlist and the cookie constraints
* [Storage modes](https://docs.scaleflex.com/developers-headless/studio/template-builder/storage-modes.md) - what each credential lets you store
* [Troubleshooting](https://docs.scaleflex.com/developers-headless/studio/template-builder/troubleshooting.md) - telling `auth` from `handshake-timeout`
