---
title: "Embedded UI Public API Reference"
slug: "embedded-ui-public-api-reference"
tags: ["embedded-ui", "reference-guides"]
status: "update"
updated: 2026-10-13T18:18:48Z
published: 2026-10-13T18:18:48Z
canonical: "docs.unqork.io/embedded-ui-public-api-reference"
---

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

# Embedded UI Public API Reference

The Embedded UI Public API is a JavaScript API that loads onto the host page when you embed an Unqork module. It exposes a `window.unqork` namespace with methods for mounting modules and workflows, authenticating users, and managing module lifecycle. This reference documents all public methods, events, and global flags.

> [!NOTE]
> If you previously used the Vega `embedded.js` API, note the following changes in Centauri: `runtime.start()` is no longer required after mounting. The `EmbeddedModule` interaction interface (`on()`, `send()`, `get()`, `swapModule()`) has been replaced by `IframeAPI`, which is available when mounting with `iframe: true`. Workflow embedding is now supported through `mountWorkflow()`.

## window.unqork

When the Embedded UI script loads, it creates a `window.unqork` namespace on the host page. This namespace holds the runtime instances the API uses for all operations. The type definition below shows the top-level shape.

```typescript
interface UnqorkGlobal {
  runtimes: {
    [runtimeId: string]: UnqorkRuntime
  }
}
```

The default runtime is accessible at `window.unqork.runtimes.default`.

## UnqorkRuntime

The `UnqorkRuntime` object is the main interface for embedding Unqork content. After loading the Embedded UI script, you access it at `window.unqork.runtimes.default`. All mounting, authentication, and lifecycle operations are methods on this object.

### Lifecycle

Call `initialize()` once before any other API calls. It loads the Angular application bundle and sets up the runtime environment.

**Field**: `initialize()` | **Type**: Method | **Returns**: `Promise<void>`

Initializes the runtime instance. Must be called before mounting any modules.

### Module Mounting

Use `mountModule()` to embed a single Unqork module into the host page. The module renders inside a Shadow DOM web component, which keeps its styles isolated from the host page's CSS. Pass `iframe: true` to embed the module in a sandboxed iframe instead. In that case, the method returns an `IframeAPI` object rather than an `HTMLElement`.

**Field**: `mountModule(options)` | **Type**: Method | **Returns**: `Promise<HTMLElement | IframeAPI>`

Mounts a single Unqork module into the host page. Returns an `IframeAPI` when `iframe` is set to `true`.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `moduleId` | `string` | Yes | The MongoDB ObjectId of the module to mount. |
| `target` | `string` | Yes | Custom element tag name or CSS selector for the mount point. |
| `style` | `string` | No | Optional style override. |
| `moduleData` | `object` | No | Pre-fetched module definition. Pass this to avoid a duplicate API call for runtime detection. |
| `iframe` | `boolean` | No | When set to `true`, mounts the module inside a sandboxed iframe instead of a Shadow DOM web component. Centauri only. Default: `false`. |
| `sandbox` | `string` | No | Custom iframe sandbox attributes. Only applies when `iframe` is set to `true`. Default: `allow-scripts allow-same-origin allow-forms`. |
| `autoLogin` | `boolean` | No | When set to `true`, automatically authenticates the user using out-of-the-box anonymous authentication. |

### Workflow Mounting

Use `mountWorkflow()` to embed a multi-step workflow instead of a single module. A workflow is an ordered sequence of modules with navigation, submission persistence, and step progress indicators.

**Field**: `mountWorkflow(options)` | **Type**: Method | **Returns**: `Promise<HTMLElement>`

Mounts a workflow (multi-step sequence of modules) into the host page.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `workflowPath` | `string` | Yes | The workflow identifier (for example, `insurance-onboarding`). |
| `target` | `string` | Yes | Custom element tag name or CSS selector for the mount point. |
| `submissionId` | `string` | No | Resumes an existing workflow from a previous save point. |
| `style` | `string` | No | Optional style override. |

### Authentication Methods

These methods handle user authentication before or after mounting a module. Call `isAuthenticated()` first to check whether the current session is already active. Then use the method that matches your authentication setup.

**Field**: `isAuthenticated()` | **Type**: Method | **Returns**: `Promise<boolean>`

Returns `true` if the current session is authenticated (through `/auth/me`).

**Field**: `authenticateAnonymous(options)` | **Type**: Method | **Returns**: `Promise<void>`

Authenticates anonymously through `/auth/customAuth`. Use this for public-facing modules that do not require a login.

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `moduleId` | `string` | Yes | The module to authenticate against. |

**Field**: `authenticateReferString(referString)` | **Type**: Method | **Returns**: `Promise<void>`

Authenticates using a refer string through `/auth/refer`.

**Field**: `getSamlEntrypointUrl(idp)` | **Type**: Method | **Returns**: `string`

Returns the SAML redirect URL for the specified identity provider. Use with an iframe or popup window for SAML-based authentication.

**Field**: `getOidcEntrypointUrl(op)` | **Type**: Method | **Returns**: `string`

Returns the OIDC redirect URL for the specified OpenID Connect provider.

**Field**: `getLoginEntrypointUrl()` | **Type**: Method | **Returns**: `string`

Returns the login form URL for iframe-based authentication.

**Field**: `waitForAuthFrameCompletion(iframe)` | **Type**: Method | **Returns**: `Promise<void>`

Returns a promise that resolves when the authentication iframe completes its flow.

**Field**: `onAuthComplete(callback)` | **Type**: Method | **Returns**: `() => void`

Registers a callback that fires when in-embed login completes. Returns an unsubscribe function.

### Module Management

Use `reloadModule()` to refresh a module that is already mounted, for example after authentication completes and the module needs to reload with the authenticated user's context.

**Field**: `reloadModule(moduleId)` | **Type**: Method | **Returns**: `Promise<void>`

Reloads an already-mounted module. Useful after authentication completes.

## Custom Events

The Embedded UI dispatches custom browser events on `window` during key lifecycle moments. Listen for these using `window.addEventListener('eventName', handler)`. The `event.detail` property contains the event payload.

| Event | Dispatched By | Detail Payload |
| --- | --- | --- |
| `unqork-embed-error` | `surfaceEmbedError()` | `{ timestamp, type, message, moduleId?, workflowPath?, originalError? }` |
| `unqork-embed-auth-complete` | Login controller | `{ user }` |
| `unqork-embed-navigate` | Link interceptor | `{ href }` |
| `unqork-embed-mounted` | spa-embed.js | `{ moduleId }` |
| `unqork-embed-workflow-mounted` | spa-embed.js | `{ workflowPath }` |

## Global Flags

The Embedded UI script sets several global properties on the host page's `window` object. Some are set automatically at startup; others are optional callbacks the host page can define before mounting.

| Flag | Type | Purpose |
| --- | --- | --- |
| `window.__UNQORK_EMBED_MODE__` | `boolean` | Set to `true` automatically when running in embedded mode. Internal code uses this to apply embed-specific behavior. |
| `window.__UNQORK_EMBED_ERROR_HANDLER__` | `function` | Optional callback set by the host page. When defined, it receives error payloads at the same time as the `unqork-embed-error` CustomEvent. |
| `window.unqork` | `object` | The public API namespace created by the Embedded UI script. |
| `window.unqorkCentauri` | `object` | Internal Centauri API. Not intended for external use. |

## `IframeAPI` - Return Value of `mountModule()` with `iframe: true`

When calling `mountModule()` with `iframe: true`, the module renders inside a sandboxed iframe rather than a Shadow DOM web component. In this mode, the method returns an `IframeAPI` object instead of an `HTMLElement`. This object lets you read and write data inside the iframe from the host page.

### Data Access

These methods let the host page read and write data inside the mounted iframe module.

| Method | Returns | Description |
| --- | --- | --- |
| `getSubmissionData(timeout?)` | `Promise<object>` | Returns all current submission data from the module. |
| `getComponentValue(componentId, timeout?)` | `Promise<any>` | Returns the current value of a specific component by its ID. |
| `setComponentValue(componentId, value, timeout?)` | `Promise<void>` | Sets the value of a specific component by its ID. |
| `getComponentDefinition(componentId, timeout?)` | `Promise<object>` | Returns the configuration definition of a specific component by its ID. |

### Actions

These methods trigger actions inside the mounted iframe module from the host page.

| Method | Returns | Description |
| --- | --- | --- |
| `triggerSubmit(timeout?)` | `Promise<void>` | Triggers module validation and submission. |

### Events

These methods let the host page subscribe to and unsubscribe from events emitted by the iframe module.

| Method | Returns | Description |
| --- | --- | --- |
| `on(eventName, callback)` | `() => void` | Subscribes to a named event. Returns an unsubscribe function. |
| `off(eventName, callback)` | `void` | Unsubscribes from a named event. |

### Supported Events through api.on()

The table below lists the events available to subscribe to through `api.on()`.

| Event | Payload | When |
| --- | --- | --- |
| `submit` | `{ submissionId, data }` | The form was submitted successfully. |
| `error` | `{ errors, message }` | A validation or submission error occurred. |
| `navigate` | `{ formId, state }` | Module navigation occurred inside the iframe. |
| `locationChange` | `{ hash }` | The URL hash changed inside the iframe. |

### Lifecycle

Use `unmount()` to remove the iframe and clean up all event listeners when the module is no longer needed.

| Method | Returns | Description |
| --- | --- | --- |
| `unmount()` | `void` | Removes the iframe from the DOM and cleans up all listeners. |

## Error Payload Shape

Every error dispatched through the `unqork-embed-error` event or bridge handler includes the following base fields. Additional fields depend on the error type. For full per-type payload details, see the [Embedded UI Error Surfacing Reference](/unqorkai/docs/embedded-ui-error-surfacing-reference).

### Base Fields

| Field | Type | Description |
| --- | --- | --- |
| `timestamp` | `string` | ISO 8601 timestamp indicating when the error occurred. |
| `type` | `string` | Error category: `http`, `angular`, `routing`, `template`, `workflow`, `workflow-fatal`, or `workflow-navigation`. |
| `message` | `string` | Human-readable description of the error. |
| `originalError` | `any` | The original error object thrown by the runtime. Useful for debugging. |

### Per-Type Fields

| Field | Type | Error Types | Description |
| --- | --- | --- | --- |
| `moduleId` | `string` | `http`, `angular`, `routing`, `template` | MongoDB ObjectId of the module where the error occurred. |
| `workflowPath` | `string` | `workflow`, `workflow-fatal`, `workflow-navigation` | Workflow path identifier. |
| `stepPath` | `string` | `workflow`, `workflow-fatal`, `workflow-navigation` | Path of the current workflow step when the error occurred. |
| `action` | `string` | `workflow-navigation` | Navigation action that failed: `next`, `previous`, or `goto`. |
| `status` | `number` | `http`, `workflow` | HTTP status code returned by the server. |
| `statusText` | `string` | `http` | HTTP status text returned by the server. |
| `url` | `string` | `http` | The request URL that returned an error. |
| `toState` | `object` | `routing` | The UI-Router state the application was trying to navigate to. |
| `fromState` | `object` | `routing` | The UI-Router state the application was navigating away from. |

---

**Changelog**

| Date | Change |
| --- | --- |
| 2026-04-21 | Initial publication. |
| 2026-06-11 | Editorial pass: removed HR dividers, added migration callout for Vega developers, added description paragraphs to all H2/H3 sections, expanded parameter and table descriptions, updated Global Flags table descriptions, added Error Payload Shape intro with link to full reference. |
| 2026-06-15 | Restructured Error Payload Shape into base fields and per-type fields; added statusText field. |

The UI (user interface) is a device's end-user interaction and communication point. It can include display screens, keyboards, and mouse. It is also how a user interacts with your application.

APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services.

JavaScript is an object-oriented computer programming language. It is most-commonly used for interactive effects in the browser.

The Vega (v 2.0.0) runtime is the next-generation engine of the UDesigner platform. Vega uses cutting-edge technologies to improve the Creator and end-user experience.

The Centauri (v 1.0.0) runtime is the first-generation foundation of the Unqork Designer Platform. Centauri provides Creators a codeless experience for developing applications.

An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity.

A definition

AngularJS is a JavaScript framework added to an HTML page with a <script> tag. AngularJS extends HTML attributes and binds data to HTML using expressions.

Rendering is the process of loading components and displaying the final result on the front-end screen.

The Shadow DOM is a web standard that allows you to create encapsulated, hidden DOM subtrees for your web components. It provides a way to scope CSS styles and JavaScript behavior within a component, preventing them from leaking out and interfering with the rest of the page.

Cascading Style Sheets (CSS) is a style sheet language used for presenting how a HTML or XML document looks to end-users.

The Document Object Model (DOM) is the data representation of objects that form the structure and content of a document on the web. The DOM represents the page.

A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.

Security Assertion Markup Language (SAML) is a protocol that allows an identity provider (IdP) to send a user's credentials to a service provider (SP) to verify their identity and grant them access to a service.

A URL (uniform resource locator) is a unique identifier used to locate a resource on the internet. Also known as a web address.

Identity provider (IdP) provide a service that creates, manages, and verifies users' digital identities, allowing them to securely authenticate and access different applications or services.

OIDC (OpenID Connect) is an identity authentication protocol that lets two applications share user information without exposing user credentials.

A key-value pair is a fundamental data structure where a unique "key" is associated with a specific "value," used for organizing and retrieving data efficiently, like in dictionaries or databases.

A JavaScript property is a member of an object that associates a key with a value. A JavaScript object is a data structure that stores a collection of properties.

An API payload is the data that is sent or received between a client and a server during an API request or response. It contains the information needed to perform actions or get resources.

Triggers activate another component when certain requirements are met. Trigger types include Concurrent, Post, and Error. Some components do not have the ability to trigger others.

A standard format for representing dates and times. ISO 8601 format is represented in the following order: year, month, day, hour, minutes, seconds, and milliseconds.

HTTP (Hypertext Transfer Protocol) is an application-layer protocol used to transmit hypermedia documents like HTML.

HTTP (Hypertext Transfer Protocol) is an application-layer protocol used to transmit hypermedia documents like HTML.