# Embed the Template Editor

> Embed the DocSpring template editor in your own application

Source: https://docspring.com/docs/guides/embedded-template-editor/
All of DocSpring's documentation: https://docspring.com/docs/llms.txt

Use the embedded template editor when your users need to set up their own PDF, Word, page design or HTML templates without leaving your application.

The embedded template editor is available on the Starter plan and higher. On the free Developer plan, the editor shows an error and its API requests return `403 Forbidden` with `"code": "upgrade_required"`. See [Plans](https://docspring.com/docs/billing/#plans).

## Setup

Include the template editor JavaScript library:

`Include template_editor.js`

```html
<script
type="text/javascript"
src="https://cdn.docspring.com/embed/template_editor.v0.1.3.js"
></script>
```

> **Note:** Enterprise deployments can load this script from the local DocSpring domain instead of the CDN: `https://docspring.yourcompany.com/assets/embed/template_editor.js`.

Render the editor inline:

`Inline embedded editor`

```html
<div id="template-editor" style="height: 720px"></div>


<script>
DocSpring.createTemplateEditor('#template-editor', {
  templateId: 'tpl_123',
  token: 'EMBED_EDIT_TOKEN',
  inline: true,
  externalUser: {
    name: 'Jane Editor',
    email: 'jane@example.com',
    external_id: 'user_123'
  },
  darkMode: false,
  doneButtonLabel: 'Done',
  onDone: function(data) {
    // Close your modal or advance to the next step.
  }
})
</script>
```

Or open it as a modal:

`Modal embedded editor`

```javascript
DocSpring.createTemplateEditor({
  templateId: 'tpl_123',
  token: 'EMBED_EDIT_TOKEN'
})
```

> **Note:** Embedded editors always edit the draft template. When the `embed_edit_allow_versioning` capability is enabled on the template, the versioning UI lets users publish, restore, or delete template versions. The embed token cannot copy a template or delete the draft. See [Security](https://docspring.com/docs/guides/embedded-template-editor/#security).

[Embedded Template Editor Example](https://docspring.com/embed_template_editor_example): Test the embedded editor with your own template ID, embed edit token, and options

## Embed Edit Token

The `token` option is the template’s embed edit token. The API returns it as `embed_edit_token` when you fetch the template, and the template editor shows it under **Embed edit token** on the template settings’ **Embedding** tab, where you can also regenerate it. See [Security](https://docspring.com/docs/guides/embedded-template-editor/#security) for what the token can and cannot do.

[API Reference: Get a Template](https://docspring.com/docs/api/#tag/templates/get/templates/{template_id}): Fetch a template, including its embed\_edit\_token

## Embed Domains

Add your domain to the template’s **Embed Domains** setting so the editor can be loaded on your pages. Enter a comma-separated list of domains, such as `example.com,app.example.com`. A wildcard such as `*.example.com` matches any subdomain, an entry such as `https://app.example.com` allows only that scheme, and an entry with a port, such as `localhost:3000`, allows only that port (an entry without one allows any port). A path, such as `example.com/editor`, is dropped when you save: only the scheme, domain and port count. Note: when **Embed Domains** is set but the embedding page sends no `Referer` or `Origin` header, the editor refuses to load. Leave the field blank only when you do not want any domain restriction. The same setting limits where the template’s [visual forms](https://docspring.com/docs/guides/embedded-forms/embedded-visual-forms/#embed-domains) and live [signature requests](https://docspring.com/docs/guides/embedded-forms/embedded-signature-requests/) load, so list the sites where you embed those too. See [Security](https://docspring.com/docs/guides/embedded-template-editor/#security) for what the embed token can and cannot do.

## Options

The first argument can be a selector string (with options as the second argument) or a single options object. When a selector is provided the editor renders inline unless you pass `inline: false`; with no selector it opens as a modal.

| Option                                       | Type    | Required | Description                                                                                                                            |
| -------------------------------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `templateId`                                 | string  | Yes      | Template ID, such as `tpl_123`.                                                                                                        |
| `token`                                      | string  | Yes      | The template’s embed edit token. See [Embed Edit Token](https://docspring.com/docs/guides/embedded-template-editor/#embed-edit-token). |
| `externalUser`                               | object  | No       | Details for the user editing the template in your app. Used for “last changed by” and version publisher labels.                        |
| `selector`                                   | string  | No       | Target element for an inline editor. May be passed here instead of as the first argument.                                              |
| `inline`                                     | boolean | No       | Defaults to `true` when a selector is provided. Pass `false` to force modal mode even with a selector.                                 |
| `darkMode`                                   | boolean | No       | Pass `true` to render the embedded editor with DocSpring’s dark theme, or `false` to force the light theme.                            |
| `showDoneButton`                             | boolean | No       | Show a customizable done button in the editor header. Defaults to `true`.                                                              |
| `doneButtonLabel`                            | string  | No       | Label for the done button. Defaults to `Done`.                                                                                         |
| `disableDoneButtonIfPredefinedFieldsMissing` | boolean | No       | Disable the done button until every `required_in_template` predefined field has been added. Defaults to `true`.                        |
| `features`                                   | object  | No       | Per-embed feature overrides.                                                                                                           |
| `closeModalOnClickOverlay`                   | boolean | No       | In modal mode, close the editor when the overlay behind it is clicked. Defaults to `true`.                                             |
| `fullScreenModal`                            | boolean | No       | In modal mode, remove the default side margins and use the full viewport width. Defaults to `false`.                                   |
| `modalMaxWidth`                              | string  | No       | In modal mode, cap the iframe width with a CSS length such as `1200px` or `80vw`. Defaults to no max width.                            |
| `iframeClass`                                | string  | No       | Additional class names for the iframe.                                                                                                 |
| `iframeStyle`                                | string  | No       | Additional inline CSS for the iframe.                                                                                                  |
| `editorURL`                                  | string  | No       | Override the iframe URL. This is mainly useful for local development or custom routing.                                                |
| `region`                                     | string  | No       | Use a DocSpring region: `US` or `EU`. Defaults to `US`.                                                                                |
| `host`                                       | string  | No       | Use one host for both app and API URLs, usually for single-domain enterprise deployments.                                              |
| `appHost`                                    | string  | No       | Override the app host used for the editor iframe, usually for split-domain enterprise deployments.                                     |
| `apiHost`                                    | string  | No       | Override the API host for consistency with other embedded libraries.                                                                   |

## Region and custom host

Use `region` when your account is in the EU region:

`Regional embedded editor`

```javascript
DocSpring.createTemplateEditor('#template-editor', {
templateId: 'tpl_123',
token: 'EMBED_EDIT_TOKEN',
region: 'EU'
})
```

For single-domain enterprise deployments, use `host`:

`Enterprise host`

```javascript
DocSpring.createTemplateEditor('#template-editor', {
templateId: 'tpl_123',
token: 'EMBED_EDIT_TOKEN',
host: 'https://docspring.example.com'
})
```

For split-domain deployments, use `appHost` and `apiHost`. Existing globals such as `DocSpring.appHost`, `DocSpring.host`, `DocSpring.scheme`, and `DocSpring.port` are still supported. If you pass `editorURL`, that full URL takes precedence and is also used to verify messages from the iframe.

`externalUser` supports these fields:

| Field         | Type   | Description                                                                |
| ------------- | ------ | -------------------------------------------------------------------------- |
| `name`        | string | Display name for editor attribution. Defaults to `Embedded Template User`. |
| `email`       | string | Email address for editor attribution metadata.                             |
| `external_id` | string | Your application’s stable user ID.                                         |

If `externalUser` is omitted, embedded saves and published versions are attributed to `Embedded Template User`.

## Return value

`DocSpring.createTemplateEditor` returns an object you can use to control the editor:

| Property | Type     | Description                                                                      |
| -------- | -------- | -------------------------------------------------------------------------------- |
| `iframe` | element  | The created `<iframe>` element.                                                  |
| `close`  | function | Closes the editor, removes its iframe and message listener, and fires `onClose`. |
| `url`    | string   | The full editor URL loaded in the iframe.                                        |

> **Note:** Only one embedded template editor should be active on a page. Creating a new editor closes the previous editor instance first. Modal editors close automatically after `onDone` and `onEvent` run. Use the returned `close()` function (or `DocSpring.closeTemplateEditor()`) when you need to close an editor from another part of your application.

## Events

`Event callbacks`

```javascript
DocSpring.createTemplateEditor('#template-editor', {
  templateId: 'tpl_123',
  token: 'EMBED_EDIT_TOKEN',
  inline: true,
  onLoad: function(data) {},
  onSave: function(data) {},
  onVersionPublish: function(data) {},
  onVersionRestore: function(data) {},
  onVersionDelete: function(data) {},
  onDocumentUpdate: function(data) {},
  onDone: function(data) {},
  onError: function(error) {},
  onClose: function() {},
  onEvent: function(eventName, data) {}
})
```

Each event has a named callback (`onLoad`, `onSave`, and so on). `onEvent` is a catch-all that fires for every event with the event name and its data. `onClose` fires whenever the editor is closed, including when you call `close()` or create a new editor. Version events only fire when versioning is enabled for the embed.

`onError` receives an object with a `message` and the HTTP `status`. When a save is rejected because of a problem with the template, such as a [formula](https://docspring.com/docs/template-editor/formulas/) that can’t be calculated, `errors` lists each problem.

The Done button only fires `onDone` when the editor has no pending changes, no active save request, and no save error. Host applications can use `onSave` to observe successful saves and `onDone` to advance or close the editor after the user clicks Done. If a save fails, the editor keeps Done disabled until the save error is resolved.

## Version Attribution

The API names who published each version in its `published_by`, in the template’s `versions`, and who last changed the draft in the template’s `last_changed_by`. Both have these fields, and are null when that wasn’t recorded:

| Field         | Description                                                                                                          |
| ------------- | -------------------------------------------------------------------------------------------------------------------- |
| `type`        | `user` for a user in your DocSpring account, `api` for an API token, or `external_user` for an embedded editor user. |
| `user_id`     | The DocSpring user’s ID (`usr_...`) for `user`, and null otherwise.                                                  |
| `external_id` | Your `externalUser.external_id` for `external_user`, and null when you didn’t provide one.                           |
| `name`        | The DocSpring user’s name, or the name you gave the embedded editor user.                                            |
| `email`       | The email address you gave the embedded editor user, for `external_user`.                                            |

API v1 returns them as flat fields on each version: `published_by_type`, `published_by_user_id`, `published_by_external_id`, `published_by_name` and `published_by_email`.

## Security

The embed edit token is a **per-template edit credential**, not a read-only key. Anyone holding it can edit the template through the embed API, and it is not a hidden secret: it appears in the editor URL and is returned in authenticated API responses. Treat it like an API key scoped to a single template and never expose a token for a template the end user should not be able to edit.

By default the token can only edit template **content** — fields, field layout, name, defaults, predefined fields, and HTML/SCSS. Three per-template capability flags (all default `false`) widen what an embed may do. They are enforced on the server, so they are the real boundary; the `features` options only control which controls are shown.

| Capability                              | Default | Allows the embed to…                                                                                                                                                               |
| --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `embed_edit_allow_settings`             | `false` | Edit template settings such as the webhook URL, redirect URL, encryption password, public access, and expiration. These settings apply to every published version of the template. |
| `embed_edit_allow_versioning`           | `false` | Publish, restore, and delete versions, and view version history.                                                                                                                   |
| `embed_edit_allow_document_replacement` | `false` | Upload a replacement PDF document.                                                                                                                                                 |

Set these with the authenticated API or in the dashboard. The matching `features` switches (`showSettings`, `showVersions`, `allowPdfReplacement`) are forced off when their capability is disabled, so a host cannot re-enable a disabled capability from the browser.

When `embed_edit_allow_settings` is `false`, the embedded editor also receives sanitized settings values in its boot payload and template JSON responses. Sensitive settings such as webhook URLs, Slack webhook URLs, redirect URLs, and PDF encryption passwords are returned as `null` or safe defaults. Enable `embed_edit_allow_settings` only when the embedded user should both view and edit those settings.

The embedded editor never receives the template’s embed domains, its permanent document URL, or the email address or external ID of the user who last changed or published it. It receives the template’s version history only when `embed_edit_allow_versioning` is `true`, and each version then names its publisher without their email address or external ID.

Regardless of any capability, the embed token **cannot** change the template’s **Embed Domains**, change the capability flags, lock the template, rotate its own token, copy the template, or delete the draft / entire template family. Those actions require account authentication (the dashboard or the authenticated API).

**Embed Domains** only restricts which origins may frame the editor (the iframe HTML load); it does not gate the JSON API, which is authenticated by the token. We recommend always setting **Embed Domains** in production.

[Customize the Embedded Template Editor](https://docspring.com/docs/guides/embedded-template-editor/customize-embedded-template-editor/): Control which editor features are available in an embed

[Template Editor Changelog](https://docspring.com/docs/changelogs/template-editor-js/): Changelog entries for the Template Editor JavaScript library
