---
title: "How to: Embed Unqork in an External Application"
slug: "embedded-ui-how-to-embed-unqork-in-an-external-application"
description: "Learn to embed Unqork applications into external sites with the Embedded UI feature. Follow our guide for setup and authentication steps."
updated: 2026-02-06T16:49:48Z
published: 2026-02-17T17:28:33Z
canonical: "docs.unqork.io/embedded-ui-how-to-embed-unqork-in-an-external-application"
---

> ## 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.

# How to: Embed Unqork in an External Application

> [!WARNING]
> The Embedded UI feature is intended for developers who have a strong understanding of the Unqork Designer Platform and JavaScript.

Learn how to **embed an Unqork application** or [module](/v1/docs/what-is-a-module) into an external website or application using the [Embedded UI](/v1/docs/introduction-to-the-embedded-user-interface-ui) feature.

> [!NOTE]
> Embedded UI is currently in open beta. Please contact your Unqork representative for more details and access.

## Enabling and Embedding the Unqork User Interface

To enable and embed an Unqork User Interface, you'll do the following:

1. Enable the Cross-Orgin Resource Sharing (CORS) setting.
2. Insert the `embedded.js` file into the host application.
3. Initialize the Unqork runtime.
4. Authenticate Users.
5. Mount an Unqork module.
6. (Optional) Build Interactions With the Unqork Module.

Learn more about each step below.

### Enable Cross-Origin Resource Sharing (CORS)

First, grant Unqork access to the host application or website. This is an important security step that prevents other applications from accessing your Unqork application.

1. At the top right of the Unqork Designer Platform, click **Administration**.
2. Under Environment, select **Environment Administration**.
3. Scroll down to the **Cross-Origin Resource Sharing (CORS)** section.
4. In the **Allowed Origins List** field, enter the location(s) where you want to embed your content.

> [!WARNING]
> Enter commas to separate more than one location. For example, `https://example1.com, https://example2.com`.

![](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/Embedded_UI_CORS_thumb_0_0.jpg?sv=2026-02-06&spr=https&st=2026-11-08T03%3A56%3A53Z&se=2026-11-08T04%3A56%3A53Z&sr=c&sp=r&sig=Sc%2FkgXaQ1Ob2O4wSEgYh1nq34pCZj35BuLyk777RBk4%3D)

### Insert `embedded.js` Into the Host Application

Next, add the JavaScript file in the host application's HTML `<head>` section. The most common way to achieve this task is by adding a script tag into the HTML page.

In the host application:

1. Insert the following into the host application's HTML file: `&lt;script src="https://&lt;unqork-express-environment&gt;/embedded.js&lt;/script&gt;`, where <unqork-express-environment> is the name of your Unqork express environment. For example, `&lt;script src="https://trainingx.unqork.io/embedded.js&lt;/script&gt;`.

After loading the file, all the necessary functionality becomes available on the global `window.unqork` object. You can access the default runtime instance using the following declaration:

```javascript
const runtime = window.unqork.runtimes.default;
```

### Initialize Runtime

This step initializes the Unqork runtime instance.

1. Run the following keyword operator:

```javascript
await runtime.initialize()
```

> [!NOTE]
> The `await` keyword must be used in an `async` function and cannot be used in the top-level scope.

### Authenticate Into the Unqork Environment

For the Unqork application to render and communicate with the platform, a valid authentication session is required. The `EmbeddedRuntime` provides several authentication methods:

- SAML
- OIDC
- Unqork Login
- Unqork Refer Auth
- Anonymous

> For more details on authentication methods, view our [Embedded UI: Understanding the embedded.js File](/v1/docs/embedded-ui-understanding-the-embeddedjs-file) article.

Here's an example of how to check for an existing session and initiate SAML authentication if the user is not logged in:

```javascript
if (!await runtime.isAuthenticated()) {
  const entrypointUrl = runtime.getSamlEntrypointUrl('https://example.com')
  const link = document.createElement('a')
  link.style='cursor:pointer'
  link.innerText = 'You are not logged in. Click here to log in using My IdP.'
  document.getElementsByTagName('auth')[0].appendChild(link)
  const authFrame = await new Promise(resolve => {
    link.onclick = () => resolve(window.open(entrypointUrl, 'popup', 'popup=true'))
  })
  await runtime.waitForAuthFrameCompletion(authFrame)
  authFrame.close()
  link.remove()
}
```

### Mount the Unqork Application

After authentication, create a DOM element in your HTML page to serve as the mount target for the Unqork application. This element must be a valid custom tag.

Creators can use standard JavaScript try/catch blocks to intercept these errors, enabling user-friendly messages or other customized error handling logic for a better end-user experience.

> [!TIP]
> This functionality is a recent change. To learn more, view our [8.0.0 Release Notes](/v1/docs/800-platform-release-notes).

1. In the HTML of the host application, insert a valid custom tag. For example, `&lt;unqork-app&gt;&lt;/unqork-app&gt;`.
2. Use the `mountModule()` method to insert the Unqork application and render it:

```javascript
const module = await runtime.mountModule({
  // Your custom element to target and display the module.
  target: 'unqork-app',
  // The module's module ID.
  moduleId: '654bd77da2f5afd918d9abe6',
  // Add an optional style to override the default style.
  style: 'style1'
})
// Start the runtime.
start()
```

The Unqork module's Express View displays in the host application or browser.

### (Optional) Build Interactions With the Unqork Module

Once the module renders, developers can interact with it in real time using the `EmbeddedModule` interface. This allows developers to retrieve data from the module or trigger actions in it to achieve the desired behavior.

> For a full list of available methods, view our [Embedded UI: Understanding the embedded.js File](/v1/docs/embedded-ui-understanding-the-embeddedjs-file) article.

Here's an example of how to send data to a module's components:

```typescript
interface EmbeddedModule {
  moduleId: string
  ready(callback: () => void): Promise<void>
  on(event: EventType | RuntimeDataUpdatedEvent, callback: (eventData?: any) => void): void
  send(event: "submission_data" | "operation", data: unknown, context?: any): Promise<void>
  get(data: RuntimeDataType): any
  validate(): Promise<void>
  swapModule(module: AnyModuleDefinition, submissionData?: SubmissionData): Promise<void>
  registerSubmissionHandler(handler: ModuleSubmissionHandler): void
  unregisterSubmissionHandler(): void
  registerValidationHandler(handler: ModuleValidationHandler): void
  unregisterValidationHandler(): void
  removeSubscriptions(): void
  destroy(): Promise<void>
}
```

## Resources

### [Introduction to the Embedded User Interface (UI)](/v1/docs/introduction-to-the-embedded-user-interface-ui)

Learn how the Embedded UI feature works and discover frequently asked questions (FAQ).

### [Understand the embedded.js File](/v1/docs/introduction-to-the-embedded-user-interface-ui)

Review the script that embeds the runtime API into an external application web page

### [Understand the EmbeddedModule Interface](/v1/docs/embedded-ui-understanding-the-embeddedmodule-interface)

View the methods that enable you to interact with an Unqork module in real time

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

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.

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

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.

Also known as Unqork Users, or Designer Users; is anyone who is inside the Unqork platform.

End-users, also known as Express Users, are the individuals accessing an application through Express View. In most cases, end-users are the customers using the product.

Express View is how your end-user views your application. Express View also lets you preview your applications to test your configuration and view the styling. This is also the view your end-users will see when interacting with your application. After configuring a module, click Preview in the Module Builder to interact with the module in Express View.