omni-embed

Omni Embed

Embed Omni dashboards in external applications using signed iframe URLs. The @omni-co/embed SDK handles URL signing and theme customization. Omni's postMessage events enable two-way communication between the parent app and embedded iframe.

Tip: Use omni-content-explorer to find dashboards to embed, and omni-admin to manage embed user permissions and user attributes for row-level security.

Prerequisites

npm install @omni-co/embed

export OMNI_BASE_URL="https://yourorg.embed-omniapp.co"   # Embed domain
export OMNI_EMBED_SECRET="your-embed-secret"               # Admin → Embed
export OMNI_API_KEY="your-api-key"                         # For user/content API calls

The embed secret is found in Admin → Embed in your Omni instance. The OMNI_BASE_URL for embedding uses the .embed-omniapp.co domain, not the standard .omniapp.co domain.

API Discovery

When unsure whether an endpoint or parameter exists, fetch the OpenAPI spec:

curl -L "$OMNI_BASE_URL/openapi.json" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Use this to verify endpoints, available parameters, and request/response schemas before making calls.

Signing Embed URLs

Use embedSsoDashboard() from the @omni-co/embed SDK to generate a signed URL server-side, then load it in an iframe client-side.

import { embedSsoDashboard, EmbedSessionMode } from "@omni-co/embed";

const embedUrl = await embedSsoDashboard({
  contentId: "dashboard-uuid",
  secret: process.env.OMNI_EMBED_SECRET,
  host: "yourorg.embed-omniapp.co",       // Hostname only, no https://
  externalId: "user@example.com",
  name: "Jane Doe",
  userAttributes: { brand: ["Acme"] },     // For row-level security
  mode: EmbedSessionMode.SingleContent,
  prefersDark: "false",
});

Parameters

Parameter	Required	Description
contentId	Yes	Dashboard UUID (from URL or Admin → Dashboards)
secret	Yes	Embed secret from Admin → Embed
host	Yes	Embed hostname only — no protocol, no port
externalId	Yes	Unique user identifier (typically email)
name	Yes	Display name for the user
userAttributes	No	Record<string, string[]> for row-level security
mode	No	SingleContent (default) or Application (enables create)
prefersDark	No	"true" or "false" — controls light/dark mode
customTheme	No	Theme object (see Custom Themes below)
entity	No	Entity name for workspaces (see Entity Workspaces below)

Gotcha: The host parameter must be a bare hostname (e.g., yourorg.embed-omniapp.co). Including a protocol (https://) or port (:3000) causes Omni to return 400.

Custom Themes

Pass a customTheme object to embedSsoDashboard() to style the embedded dashboard content (tile backgrounds, text colors, controls, buttons). This controls what's inside the iframe — parent app styling is separate.

const embedUrl = await embedSsoDashboard({
  // ...signing params
  prefersDark: "false",
  customTheme: {
    "dashboard-background": "#FEF2F2",
    "dashboard-tile-background": "#FFF5F5",
    "dashboard-key-color": "#E60000",
    "dashboard-key-text-color": "#ffffff",
    // ...
  },
});

Property Reference

Page:

Property	Description
dashboard-background	Dashboard page background
dashboard-page-padding	Dashboard page padding

Tiles:

Property	Description
dashboard-tile-margin	Spacing around tiles
dashboard-tile-background	Tile background color
dashboard-tile-shadow	Tile box shadow
dashboard-tile-text-body-color	Primary text color in tiles
dashboard-tile-text-secondary-color	Secondary text color in tiles
dashboard-tile-border-color	Tile border color
dashboard-tile-border-radius	Tile border radius
dashboard-tile-border-style	Tile border style
dashboard-tile-border-width	Tile border width
dashboard-tile-title-font-size	Title font size
dashboard-tile-title-font-weight	Title font weight
dashboard-tile-title-text-color	Title text color
dashboard-tile-title-font-family	Custom title font (woff2 URL)
dashboard-tile-text-body-font-family	Custom body font
dashboard-tile-text-code-font-family	Custom code font

Controls (filter dropdowns):

Property	Description
dashboard-control-background	Filter control background
dashboard-control-radius	Filter control border radius
dashboard-control-border-color	Filter control border color
dashboard-control-text-color	Filter control text color
dashboard-control-placeholder-color	Placeholder text color
dashboard-control-label-color	Label text above controls
dashboard-control-outline-color	Focus outline color

Control Popovers (dropdown menus):

Property	Description
dashboard-control-popover-background	Popover background
dashboard-control-popover-text-color	Popover text color
dashboard-control-popover-secondary-text-color	Secondary text in popovers
dashboard-control-popover-link-color	Link color in popovers
dashboard-control-popover-divider-color	Divider color
dashboard-control-popover-radius	Popover border radius
dashboard-control-popover-border-color	Popover border color
dashboard-filter-input-background	Filter input background
dashboard-filter-input-radius	Filter input border radius
dashboard-filter-input-border-color	Filter input border color
dashboard-filter-input-text-color	Filter input text color
dashboard-filter-input-placeholder-color	Placeholder text
dashboard-filter-input-icon-color	Icon color in filter inputs
dashboard-filter-input-outline-color	Focus outline for filter inputs
dashboard-filter-input-accent-color	Checkbox, radio, and toggle color
dashboard-filter-input-accent-invert-color	Checkmark/dot color inside inputs
dashboard-filter-input-token-color	Multi-select token background
dashboard-filter-input-token-text-color	Multi-select token text color

Buttons:

Property	Description
dashboard-key-color	Primary action color (Update buttons)
dashboard-key-text-color	Text color on primary buttons
dashboard-button-radius	Button border radius
dashboard-button-transparent-text-color	Transparent button text color
dashboard-button-transparent-interactive-color	Transparent button hover color
dashboard-menu-item-interactive-color	Menu item hover background

Supported CSS Values

• Hex colors: "#FEF2F2", "#E60000"
• Box shadows with rgba: "0 2px 8px rgba(230, 0, 0, 0.1)"
• Custom fonts via URL: "url(https://fonts.gstatic.com/...) format('woff2')"
• Empty strings to clear defaults: ""
• linear-gradient() and rgba() for backgrounds work in Omni's UI theme editor but may fail when passed via the SDK — use solid hex colors for reliability

Theming Tips

For effective branding, tint backgrounds throughout rather than only coloring buttons:

• dashboard-background → light brand tint (like Tailwind's color-50)
• dashboard-tile-background → slightly lighter than page background
• dashboard-tile-title-text-color → brand primary (titles in brand color)
• dashboard-control-label-color → brand primary (labels in brand color)
• dashboard-tile-border-color → medium-light brand tint (like color-200)
• dashboard-key-color → brand primary
• dashboard-filter-input-accent-color → brand primary (checkboxes, toggles)

Embed Events

Omni communicates with the parent app via postMessage. All Omni events have source: "omni".

Listening for Events

window.addEventListener("message", (event) => {
  if (event.data?.source !== "omni") return;

  switch (event.data.name) {
    case "dashboard:loaded":
      // Dashboard ready
      break;
    case "error":
      // Handle error
      break;
    case "dashboard:tile-drill":
      // Handle drill action
      break;
  }
});

Event Reference

dashboard:loaded — Fired when the embedded dashboard finishes loading.

{ "source": "omni", "name": "dashboard:loaded" }

dashboard:filters — Fired when filter state changes inside the embedded dashboard.

{
  "source": "omni",
  "name": "dashboard:filters",
  "payload": { /* filter state */ }
}

error — Fired when a detectable error occurs on the embedded page.

{
  "source": "omni",
  "name": "error",
  "payload": {
    "href": "https://...",
    "message": "Error description"
  }
}

dashboard:tile-drill — Fired when a user drills on any dashboard tile (charts, tables, maps). No Omni-side configuration required.

{
  "source": "omni",
  "name": "dashboard:tile-drill",
  "payload": {
    "userId": "string",
    "dashboard": {
      "filters": {
        "filterName": {
          "filter": {},
          "asJsonUrlSearchParam": "string"
        }
      },
      "href": "string",
      "urlId": "string",
      "path": "string",
      "title": "string"
    },
    "tile": {
      "id": "string",
      "title": "string",
      "appliedFilters": {
        "filterName": {
          "filter": {},
          "asJsonUrlSearchParam": "string"
        }
      }
    },
    "drill": {
      "field": "string",
      "fieldLabel": "string",
      "drillQueryLabel": "string",
      "rowToDrill": { "field_name": "value" }
    }
  }
}

Use drill.rowToDrill for the data from the drilled row. Use asJsonUrlSearchParam from tile.appliedFilters or dashboard.filters to sign and embed a different dashboard with those filters applied.

page:changed — Fired when the URL changes inside the iframe (including after saving a new dashboard).

{
  "source": "omni",
  "name": "page:changed",
  "payload": {
    "pathname": "string",
    "type": "string"
  }
}

Custom visualization events — Fired when a user clicks a configured table row or markdown link. Requires setup in Omni: set the table column's Display to Link → Embed event and enter an event name. For markdown, use <omni-message> tags.

{
  "source": "omni",
  "name": "<your-event-name>",
  "payload": {
    "data": "comma-separated values"
  }
}

Table setup: field dropdown → Display tab → Display as: Link → URL: Embed event → enter event name.

Markdown setup:

<omni-message event-name="product-click" event-data="{{products.name.raw}},{{products.retail_price.raw}}">
  Click here
</omni-message>

Sending Events to the Iframe

dashboard:filter-change-by-url-parameter — Push a filter from the parent app into the embedded dashboard.

iframe.contentWindow.postMessage({
  source: "omni",
  name: "dashboard:filter-change-by-url-parameter",
  payload: {
    filterUrlParameter: 'f--<filter_id>={"values":["value1","value2"]}'
  }
}, iframeOrigin);

Get the filterUrlParameter string by opening the dashboard in Omni, changing filter values, and copying the f-- parameter from the URL.

Entity Workspaces

Entity workspaces let embed users create and save their own dashboards within a scoped folder.

import {
  embedSsoDashboard,
  EmbedSessionMode,
  EmbedEntityFolderContentRoles,
  EmbedUiSettings,
  EmbedConnectionRoles,
} from "@omni-co/embed";

const embedUrl = await embedSsoDashboard({
  // ...standard signing params
  entity: "acme",
  entityFolderContentRole: EmbedEntityFolderContentRoles.EDITOR,
  mode: EmbedSessionMode.Application,
  uiSettings: {
    [EmbedUiSettings.SHOW_NAVIGATION]: false,
  },
  connectionRoles: {
    "connection-uuid": EmbedConnectionRoles.RESTRICTED_QUERIER,
  },
});

Parameter	Description
entity	Entity name — scopes the user's folder (e.g., derived from email domain)
entityFolderContentRole	EDITOR lets users create/edit dashboards in their entity folder
mode	Must be Application to enable create features
uiSettings	Control Omni's built-in UI (e.g., hide Omni's sidebar if you provide your own)
connectionRoles	Grant query access: RESTRICTED_QUERIER for data exploration

Embed Users and Permissions

When building permission-aware experiences (e.g., a sidebar that only shows dashboards a user can access), use these REST API calls. Note: API calls use the .omniapp.co domain, not the .embed-omniapp.co embed domain.

Look Up an Embed User

curl -L "$OMNI_API_BASE/api/scim/v2/embed/users?filter=embedExternalId%20eq%20%22user@example.com%22" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Returns the Omni user ID for the given externalId. If no user is found, the user hasn't accessed any embedded dashboards yet.

List Documents by User Permission

curl -L "$OMNI_API_BASE/api/v1/documents?userId={omniUserId}" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Response uses records array (not documents):

{
  "pageInfo": {
    "hasNextPage": false,
    "nextCursor": null,
    "pageSize": 20,
    "totalRecords": 5
  },
  "records": [
    {
      "identifier": "fb007aa3",
      "name": "Sales Dashboard",
      "hasDashboard": true,
      "folder": {
        "id": "...",
        "name": "Sales",
        "path": "sales/regional"
      }
    }
  ]
}

Use identifier as the contentId for embed signing. Filter for hasDashboard: true to get embeddable dashboards only.

List Folders for Friendly Names

Entity folders have technical paths like omni-system-sso-embed-entity-folder-poc. Map paths to display names:

curl -L "$OMNI_API_BASE/api/v1/folders" \
  -H "Authorization: Bearer $OMNI_API_KEY"

Build a path → name mapping from the response to display user-friendly folder names.

Domain Mapping

The embed domain (.embed-omniapp.co) and API domain (.omniapp.co) are different:

Embed: yourorg.embed-omniapp.co  →  used for iframe URLs
API:   yourorg.omniapp.co        →  used for REST API calls

When your app stores the embed domain, convert it for API calls by replacing .embed-omniapp.co with .omniapp.co.

Docs Reference

• Embed Overview · Custom Themes · Embed Events · AI Chat in Embeds · Embed Users API · Documents API

Related Skills

• omni-content-explorer — find dashboards to embed
• omni-content-builder — create dashboards before embedding them
• omni-admin — manage embed user permissions, user attributes for RLS, and connections
• omni-model-explorer — understand available fields for embed event data