npm.io
1.0.0 • Published 4d ago

@omni-co/embed

Licence
MIT
Version
1.0.0
Deps
0
Size
217 kB
Vulns
0
Weekly
0
SummaryDependencyVersions

Omni Embed SSO Typescript SDK for Server (Node, etc)

Server Side Only

This SDK is intented to be used in a server context.

Your embed secret should never be shipped to a client or browser.

Anyone with access to the secret can craft an embed url and potentially gain access to your Omni instance. Guard your embed secret in the same way you would a private key.

Install

npm:

npm install @omni-co/embed

yarn:

yarn add @omni-co/embed

What's New in 1.0

embedSsoDashboard, embedSsoWorkbook and embedSsoContentDiscovery now sign a v1 payload. Every param travels inside one signed, compressed blob, so the query carries payload and signature rather than a list of loose params. The function names and props are unchanged, so most call sites don't move.

Also new:

  • embedSsoApp embeds an Omni app by content id.
  • expiresIn sets how long a generated URL stays good for. Defaults to 24 hours, 7 days maximum.
  • showHeader is a new uiSettings key that hides the top header bar.
  • The deprecated* builders still mint v0 URLs. They exist for Omni's own rollout and you should not need them — see The deprecated* v0 Builders.
Why v1 Signing

v0 signed a string rebuilt from the params, which meant the SDK and the Omni server each had to reconstruct the same bytes and agree on key order, delimiters, escaping, and empty-vs-absent. v1 computes the HMAC over the payload exactly as it travels in the URL, and the verifier checks the string it received rather than rebuilding it. Nothing is re-derived from the query string, so there is no canonicalization for the two ends to disagree about, and JSON params like userAttributes and customTheme stay real objects instead of being stringified per-param and percent-encoded.

Breaking Changes

  • embedSsoDashboard, embedSsoWorkbook and embedSsoContentDiscovery emit v1 signed-payload URLs instead of v0 URLs.
  • The domain prop is removed. Use host.
  • Generated URLs carry an expiry, 24 hours by default.
  • getSignature is now deprecatedGetSignature.

The expiry is the only one that can break a working integration without a code change.

Upgrading from 0.x

Ordered by how many people it affects. Most callers stop after the first section.

Most callers: no code changes

If you call embedSsoDashboard, embedSsoWorkbook or embedSsoContentDiscovery with the documented props, your code is unchanged. Two things change underneath it:

  • The URLs are now v1 signed payloads — a different shape on the wire, though nothing about how you call the builders changes.
  • They expire 24 hours after you mint them.

That second one is the only change that can break a working integration without you touching a line of code. If you mint URLs ahead of use, read Generated URLs now expire below.

You passed domain

Fold it into host. domain only ever worked alongside organizationName; host takes the whole hostname on its own.

- await embedSsoDashboard({ organizationName: 'omni', domain: 'example.co', ... })
+ await embedSsoDashboard({ host: 'omni.example.co', ... })
Generated URLs now expire

Default is 24 hours. If you generate URLs ahead of use — emailing them, caching them, building them in a nightly job — set a lifetime that covers the gap, or generate them on demand:

const url = await embedSsoDashboard({
  contentId: 'miU0hL6z',
  expiresIn: 60 * 60, // one hour
  externalId: 'wile.e@coyote.co',
  name: 'Wile E',
  organizationName: 'acme',
  secret: 'abcdefghijklmnopqrstuvwxyz123456',
})

Maximum is 7 days. Shorter is better: an unredeemed URL that leaks — browser history, a referer header, a screenshot, a proxy log — is a bearer credential until it expires.

You called getSignature directly

Rename it to deprecatedGetSignature. It signs v0 only, so this is a rename, not a migration — if you are verifying inbound v1 logins yourself, use unpackSignedPayload instead.

You called the Compressed builders

Drop the suffix — the plain builders now do the same thing.

- const url = await embedSsoDashboardCompressed({ ... })
+ const url = await embedSsoDashboard({ ... })

Only 0.24.0 ever exported embedSsoDashboardCompressed, embedSsoWorkbookCompressed and embedSsoContentDiscoveryCompressed. If you are coming from 0.23.0 or earlier, these names never existed and there is nothing to change.

Basic Examples

Generated URLs expire as of 1.0.0 — 24 hours from the moment you mint one, unless you pass expiresIn. See Upgrading from 0.x.

import {
  embedSsoDashboard,
  embedSsoWorkbook,
  embedSsoApp,
  embedSsoContentDiscovery,
} from '@omni-co/embed'

// This creates a signed embed sso link for a dashboard
// in the omni account named Acme.
const iframeUrl = await embedSsoDashboard({
  contentId: 'miU0hL6z',
  externalId: 'wile.e@coyote.co',
  name: 'Wile E',
  organizationName: 'acme',
  secret: 'abcdefghijklmnopqrstuvwxyz123456',
})

// Alternatively, you can create a signed embed sso link for a workbook.
const iframeUrl = await embedSsoWorkbook({
  contentId: 'miU0hL6z',
  externalId: 'wile.e@coyote.co',
  name: 'Wile E',
  organizationName: 'acme',
  secret: 'abcdefghijklmnopqrstuvwxyz123456',
})

// Apps work the same way.
const iframeUrl = await embedSsoApp({
  contentId: 'miU0hL6z',
  externalId: 'wile.e@coyote.co',
  name: 'Wile E',
  organizationName: 'acme',
  secret: 'abcdefghijklmnopqrstuvwxyz123456',
})

// You can also create a signed embed sso link for a content discovery page.
const iframeUrl = await embedSsoContentDiscovery({
  externalId: 'wile.e@coyote.co',
  name: 'Wile E',
  path: 'root',
  organizationName: 'acme',
  secret: 'abcdefghijklmnopqrstuvwxyz123456',
})

2-step Example

// Step 1
const { success, sessionToken } = await createSessionToken({
  apiKey: "<YOUR API KEY>",
  connectionRoles: {
  "abcd1234-abcd-efgh-ijkl-abcdef123456":
    EmbedConnectionRoles.RESTRICTED_QUERIER,
  },
  contentPath: "/dashboards/abcd1234",
  externalId: "dodgers-17",
  host: "myorg.embed-omniapp.co",
  mode: EmbedSessionMode.Application,
  name: "Shohei Ohtani",
});
if (!success) throw new Error("Failed to generate session");

// Step 2
const redeemSessionUrl = await redeemSessionToken({
  host: "myorg.embed-omniapp.co",
  prefersDark: "false",
  theme: "vibes",
  secret: "<YOUR EMBED SECRET>",
  sessionToken,
});

...

<iframe src={redeemSessionUrl} />

Using Vanity Domains

// Use `host` to create a link to a vanity domain.
// Note: `organizationName` is incompatible with `host`
const iframeUrl = await embedSsoDashboard({
  contentId: 'miU0hL6z',
  externalId: 'wile.e@coyote.co',
  host: 'omni.example.com',
  name: 'Wile E',
  secret: 'abcdefghijklmnopqrstuvwxyz123456',
})

The deprecated* v0 Builders

deprecatedEmbedSsoDashboard, deprecatedEmbedSsoWorkbook, deprecatedEmbedSsoApp, deprecatedEmbedSsoContentDiscovery and deprecatedGetSignature still mint and sign v0 URLs.

You almost certainly do not want these. They are exported so Omni can keep minting v0 URLs for orgs part-way through the migration, where the choice is made per org at runtime and both formats have to be available in one process. deprecatedGetSignature is also still useful if you verify inbound v0 logins yourself.

If you are generating embed URLs, use embedSsoDashboard and friends, which sign v1. Talk to us before reaching for the deprecated* builders — v0 signs a string rebuilt from the params, and v1 exists because signing the payload as transmitted is the stronger guarantee.

They take the same props as their v1 counterparts, including expiresIn, which they accept and ignore — a v0 URL has nowhere to carry an expiry. That way one settings object can feed whichever builder a feature flag picks.

All of them go away once no org needs v0.

embedSsoDashboard

This is the type signature for the embedSsoDashboard function:

type EmbedSsoDashboardProps = {
  // Optional boolean property that toggles the dashboard's Access Boost setting.
  accessBoost?: boolean

  /**
   * Optional branch setting that sets the model branch of the embed session.
   */
  branch?: string

  /**
   * Optional object that determines the connection permissions for the embed user.
   * Keys are connection ids. Values should be connection roles — either an
   * `EmbedConnectionRoles` value or a custom role name.
   */
  connectionRoles?: Record<string, string>

  // Short GUID of the dashboard. Can be obtained via the dashboard's url.
  contentId: string

  // Optional custom theme object that styles the embedded dashboard.
  customTheme?: CustomThemeProperties

  /**
   * Optional custom theme ID setting that styles the embedded dashboard.
   * This ID should be from a theme created within the Omni application.
   */
  customThemeId?: string

  // Optional email parameter that sets the default scheduling email for the embed user.
  email?: string

  /**
   * Optional identifier to associate the user with an external organization or system.
   * Note that each distinct entity will generate its own folder and group. These can be used by
   * an embed user to share content with other members in the same entity.
   */
  entity?: string

  /**
   * Optional AI credit limit applied to the entity group corresponding to the `entity` value. Sets the
   * entity group's AI credit cap at login time and requires `entity` to be set. A number caps the entity
   * group's AI credit usage; the string "unlimited" is an explicit no-cap override; omitting it removes
   * any existing override so the entity group falls back to the organization default.
   */
  entityAiCreditLimit?: number | 'unlimited'

  /**
   * Sets embed user content permission on the entity folder. Can be one of "MANAGER", "EDITOR", "VIEWER",
   * or "NO_ACCESS".
   *
   * MANAGER: the user will have the ability to manage content and content permissions of the entity folder.
   * EDITOR: the user will have the ability to manage content in the entity folder.
   * VIEWER: the user will only be able to view content in the entity folder.
   * NO_ACCESS: the user will have no access to content in the top-level entity folder. Note that the
   *  entityFolderGroupContentRole should also be set to NO_ACCESS in order to completely restrict access
   *  to the top-level entity folder.
   */
  entityFolderContentRole?: EmbedEntityFolderContentRoles

  /**
   * Sets embed entity group content permission on the entity folder. Can be one of "MANAGER", "EDITOR", "VIEWER",
   * or "NO_ACCESS".
   *
   * MANAGER: all users in the group will have the ability to manage content and content permissions of the entity folder.
   * EDITOR: all users in the group have the ability to manage content in the entity folder.
   * VIEWER: all users in the group are restricted to just view content in the entity folder.
   * NO_ACCESS: all users in the group will have no access to content in the top-level entity folder.
   */
  entityFolderGroupContentRole?: EmbedEntityFolderContentRoles

  /**
   * Optional setting that customizes the generated entity folder label. This only affects the
   * entity folder corresponding to the `entity` parameter value.
   */
  entityFolderLabel?: string

  /**
   * Optional setting that customizes the generated entity group label. This only affects the
   * entity group corresponding to the `entity` parameter value.
   */
  entityGroupLabel?: string

  // Required identifier to associate the external user with an automatically generated internal Omni user.
  /**
   * Optional lifetime of the generated URL, in seconds from now. Defaults to
   * 24 hours; must be positive and at most 7 days (604800). Travels as an `exp`
   * inside the signed payload.
   *
   * Shorter is better: an unredeemed URL that leaks is a bearer credential
   * until it expires.
   */
  expiresIn?: number

  externalId: string

  /**
   * Optional url filter search parameter. Should be the same as the filter search parameters on a dashboard url.
   * Example: f--inventory_items.cost=%7B"kind"%3A"EQUALS"%2C"type"%3A"number"%2C"values"%3A%5B%5D%2C"is_negative"%3Afalse%2C"is_inclusive"%3Afalse%7D&f--users.state=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B"Aberdeen"%2C"Alabama"%5D%2C"is_negative"%3Afalse%7D&f--users.country=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B"UK"%5D%2C"is_negative"%3Afalse%7D
   *
   */
  filterSearchParam?: string

  /*
   * Optional groups array property. The array should be a list of group names from the Omni application, which the embed user will be added to.
   */
  groups?: string[]

  /**
   * Used to set the host of signed embed URL, required when using vanity domains.
   * Protocol is not required, as https is assumed.
   * Port is not accepted. If required, use the `port` prop.
   *
   * @throws Error if `organizationName` is provided.
   * @example "omni.example.com"
   * @example "omni.another-example.app"
   */
  host?: string

  /**
   * Optional link access setting to control which Omni dashboard links are shown. Note that regardless of the linkAccess value,
   * all non-Omni dashboard links will be shown and allowed in drill menus. Acceptable values include:
   *
   * "__omni_link_access_open": Special string keyword that permisses and shows all Omni dashboard links on the embedded dashboard.
   * "abcd1234,efgh5678,ijkl9999": An allowlist of dashboard IDs that permisses and shows links to the specified dashboards.
   * undefined: If left undefined, the default behavior is to hide and disallow all links to other Omni dashboards on the embedded dashboard.
   */
  linkAccess?: string

  /**
   * Optional mode setting that determines whether the entire application should be embedded or a single piece of content.
   *
   * APPLICATION: the entire application will be embedded, meaning in-app navigation and document header options will be available.
   * SINGLE_CONTENT: only the content specified in the contentId will be embedded and application mode features will be hidden.
   */
  mode?: EmbedSessionMode

  /**
   * Optional object that determines the model permissions for the embed user.
   * Keys are model ids. Values should be model roles — a base role or a custom
   * role name.
   */
  modelRoles?: Record<string, string>

  // Required name of the external user.
  name: string

  /**
   * Name of the organization the content belongs to. If provided, generates a default embed host
   * URL in the form of `https://<organizationName>.embed-omniapp.co`.
   *
   * @throws Error if `host` is provided.
   */
  organizationName?: string

  // Port of host.
  port?: number

  // Optional dark mode setting. Can be one of "true", "false", or "system".
  prefersDark?: string

  /**
   * When true, an existing content role for the embed user on the entity folder will not be overwritten
   * by the `entityFolderContentRole` value. If a content role does not exist on the entity folder for the embed user,
   * the `entityFolderContentRole` value will be applied.
   */
  preserveEntityFolderContentRole?: boolean

  // Signing secret available to Omni admins.
  secret: string

  // Optional theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
  theme?: string

  /**
   * Optional IANA timezone for the embed session (eg "America/New_York"). Unsupported values
   * are silently dropped by the Omni server and the login still succeeds. This does not update
   * the embed user's `omni_user_timezone` attribute — use `userAttributes` for that.
   */
  timezone?: string

  // Optional UI settings object to control appearance of embed experience.
  uiSettings?: EmbedUiSettingsObject

  /**
   * Optional user attributes to be passed to user associated with the
   * externalId. User attributes must be created in Omni before being
   * defined and given a value here.
   */
  userAttributes?: Record<string, string | string[] | number | number[]>
}

embedSsoWorkbook

This is the type signature for the embedSsoWorkbook function:

type EmbedSsoWorkbookProps = {
  /**
   * Optional branch setting that sets the model branch of the embed session.
   */
  branch?: string

  /**
   * Optional object that determines the connection permissions for the embed user.
   * Keys are connection ids. Values should be connection roles — either an
   * `EmbedConnectionRoles` value or a custom role name.
   */
  connectionRoles?: Record<string, string>

  /**
   * Short GUID of the workbook.
   *
   * Can be obtained via the workbook's share -> embed -> iframe url or via the dashboard url.
   * This will embed the workbook associated with the dashboard id.
   */
  contentId: string

  /**
   * Optional custom theme object. Note that this theme will only apply to dashboards viewed
   * during the generated embed session.
   */
  customTheme?: CustomThemeProperties

  /**
   * Optional custom theme ID setting. Note that this theme will only apply to dashboards viewed
   * during the generated embed session.
   */
  customThemeId?: string

  // Optional email parameter that sets the default scheduling email for the embed user.
  email?: string

  /**
   * Optional identifier to associate the user with an external organization or system.
   * Note that each distinct entity will generate its own folder and group. These can be used by
   * an embed user to share content with other members in the same entity.
   */
  entity?: string

  /**
   * Optional AI credit limit applied to the entity group corresponding to the `entity` value. Sets the
   * entity group's AI credit cap at login time and requires `entity` to be set. A number caps the entity
   * group's AI credit usage; the string "unlimited" is an explicit no-cap override; omitting it removes
   * any existing override so the entity group falls back to the organization default.
   */
  entityAiCreditLimit?: number | 'unlimited'

  /**
   * Sets embed user content permission on the entity folder. Can be one of "MANAGER", "EDITOR", "VIEWER",
   * or "NO_ACCESS".
   *
   * MANAGER: the user will have the ability to manage content and content permissions of the entity folder.
   * EDITOR: the user will have the ability to manage content in the entity folder.
   * VIEWER: the user will only be able to view content in the entity folder.
   * NO_ACCESS: the user will have no access to content in the top-level entity folder. Note that the
   *  entityFolderGroupContentRole should also be set to NO_ACCESS in order to completely restrict access
   *  to the top-level entity folder.
   */
  entityFolderContentRole?: EmbedEntityFolderContentRoles

  /**
   * Sets embed entity group content permission on the entity folder. Can be one of "MANAGER", "EDITOR", "VIEWER",
   * or "NO_ACCESS".
   *
   * MANAGER: all users in the group will have the ability to manage content and content permissions of the entity folder.
   * EDITOR: all users in the group have the ability to manage content in the entity folder.
   * VIEWER: all users in the group are restricted to just view content in the entity folder.
   * NO_ACCESS: all users in the group will have no access to content in the top-level entity folder.
   */
  entityFolderGroupContentRole?: EmbedEntityFolderContentRoles

  /**
   * Optional setting that customizes the generated entity folder label. This only affects the
   * entity folder corresponding to the `entity` parameter value.
   */
  entityFolderLabel?: string

  /**
   * Optional setting that customizes the generated entity group label. This only affects the
   * entity group corresponding to the `entity` parameter value.
   */
  entityGroupLabel?: string

  // Required identifier to associate the external user with an
  // automatically generated internal Omni user.
  /**
   * Optional lifetime of the generated URL, in seconds from now. Defaults to
   * 24 hours; must be positive and at most 7 days (604800). Travels as an `exp`
   * inside the signed payload.
   *
   * Shorter is better: an unredeemed URL that leaks is a bearer credential
   * until it expires.
   */
  expiresIn?: number

  externalId: string

  // Optional url filter search parameter. Should be the same as the filter search parameters on a dashboard url.
  // Example: f--inventory_items.cost=%7B"kind"%3A"EQUALS"%2C"type"%3A"number"%2C"values"%3A%5B%5D%7D
  filterSearchParam?: string

  /*
   * Optional groups array property. The array should be a list of group names from the Omni application, which the embed user will be added to.
   */
  groups?: string[]

  /**
   * Used to set the host of signed embed URL, required when using vanity domains.
   * Protocol is not required, as https is assumed.
   * Port is not accepted. If required, use the `port` prop.
   *
   * @throws Error if `organizationName` is provided.
   * @example "omni.example.com"
   * @example "omni.another-example.app"
   */
  host?: string

  // Optional link access setting to control link security on embedded content. Note that regardless of the linkAccess value,
  // all non-Omni dashboard links will be shown and allowed in drill menus. Acceptable values include:
  // "__omni_link_access_open": Special string keyword that permisses and shows all Omni dashboard links on the embedded dashboard.
  // "abcd1234,efgh5678,ijkl9999": An allowlist of dashboard IDs that permisses and shows links to the specified dashboards.
  // undefined: If left undefined, the default behavior is to hide and disallow all links to other Omni dashboards on the embedded dashboard.
  linkAccess?: string

  /**
   * Optional mode setting that determines whether the entire application should be embedded or a single piece of content.
   *
   * APPLICATION: the entire application will be embedded, meaning in-app navigation and document header options will be available.
   * SINGLE_CONTENT: only the content specified in the contentId will be embedded and application mode features will be hidden.
   */
  mode?: EmbedSessionMode

  /**
   * Optional object that determines the model permissions for the embed user.
   * Keys are model ids. Values should be model roles — a base role or a custom
   * role name.
   */
  modelRoles?: Record<string, string>

  // Required name of the external user.
  name: string

  /**
   * Name of the organization the content belongs to. If provided, generates a default embed host
   * URL in the form of `https://<organizationName>.embed-omniapp.co`.
   *
   * @throws Error if `host` is provided.
   */
  organizationName?: string

  // Port of host.
  port?: number

  // Optional dark mode setting. Can be one of "true", "false", or "system".
  prefersDark?: string

  /**
   * When true, an existing content role for the embed user on the entity folder will not be overwritten
   * by the `entityFolderContentRole` value. If a content role does not exist on the entity folder for the embed user,
   * the `entityFolderContentRole` value will be applied.
   */
  preserveEntityFolderContentRole?: boolean

  // Signing secret available to Omni admins.
  secret: string

  // Optional theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
  theme?: string

  /**
   * Optional IANA timezone for the embed session (eg "America/New_York"). Unsupported values
   * are silently dropped by the Omni server and the login still succeeds. This does not update
   * the embed user's `omni_user_timezone` attribute — use `userAttributes` for that.
   */
  timezone?: string

  // Optional UI settings object to control appearance of embed experience.
  uiSettings?: EmbedUiSettingsObject

  /**
   * Optional user attributes to be passed to user associated with the
   * externalId. User attributes must be created in Omni before being
   * defined and given a value here.
   */
  userAttributes?: Record<string, string | string[] | number | number[]>
}

embedSsoApp

This is the type signature for the embedSsoApp function:

type EmbedSsoAppProps = {
  /**
   * Optional branch setting that sets the model branch of the embed session.
   */
  branch?: string

  /**
   * Optional object that determines the connection permissions for the embed user.
   * Keys are connection ids. Values should be connection roles — either an
   * `EmbedConnectionRoles` value or a custom role name.
   */
  connectionRoles?: Record<string, string>

  /**
   * Short GUID of the app. Can be obtained via the app's url.
   */
  contentId: string

  /**
   * Optional custom theme object. Note that this theme will only apply to dashboards viewed
   * during the generated embed session.
   */
  customTheme?: CustomThemeProperties

  /**
   * Optional custom theme ID setting. Note that this theme will only apply to dashboards viewed
   * during the generated embed session.
   */
  customThemeId?: string

  // Optional email parameter that sets the default scheduling email for the embed user.
  email?: string

  /**
   * Optional identifier to associate the user with an external organization or system.
   * Note that each distinct entity will generate its own folder and group. These can be used by
   * an embed user to share content with other members in the same entity.
   */
  entity?: string

  /**
   * Optional AI credit limit applied to the entity group corresponding to the `entity` value. Sets the
   * entity group's AI credit cap at login time and requires `entity` to be set. A number caps the entity
   * group's AI credit usage; the string "unlimited" is an explicit no-cap override; omitting it removes
   * any existing override so the entity group falls back to the organization default.
   */
  entityAiCreditLimit?: number | 'unlimited'

  /**
   * Sets embed user content permission on the entity folder. Can be one of "MANAGER", "EDITOR", "VIEWER",
   * or "NO_ACCESS".
   *
   * MANAGER: the user will have the ability to manage content and content permissions of the entity folder.
   * EDITOR: the user will have the ability to manage content in the entity folder.
   * VIEWER: the user will only be able to view content in the entity folder.
   * NO_ACCESS: the user will have no access to content in the top-level entity folder. Note that the
   *  entityFolderGroupContentRole should also be set to NO_ACCESS in order to completely restrict access
   *  to the top-level entity folder.
   */
  entityFolderContentRole?: EmbedEntityFolderContentRoles

  /**
   * Sets embed entity group content permission on the entity folder. Can be one of "MANAGER", "EDITOR", "VIEWER",
   * or "NO_ACCESS".
   *
   * MANAGER: all users in the group will have the ability to manage content and content permissions of the entity folder.
   * EDITOR: all users in the group have the ability to manage content in the entity folder.
   * VIEWER: all users in the group are restricted to just view content in the entity folder.
   * NO_ACCESS: all users in the group will have no access to content in the top-level entity folder.
   */
  entityFolderGroupContentRole?: EmbedEntityFolderContentRoles

  /**
   * Optional setting that customizes the generated entity folder label. This only affects the
   * entity folder corresponding to the `entity` parameter value.
   */
  entityFolderLabel?: string

  /**
   * Optional setting that customizes the generated entity group label. This only affects the
   * entity group corresponding to the `entity` parameter value.
   */
  entityGroupLabel?: string

  // Required identifier to associate the external user with an
  // automatically generated internal Omni user.
  /**
   * Optional lifetime of the generated URL, in seconds from now. Defaults to
   * 24 hours; must be positive and at most 7 days (604800). Travels as an `exp`
   * inside the signed payload.
   *
   * Shorter is better: an unredeemed URL that leaks is a bearer credential
   * until it expires.
   */
  expiresIn?: number

  externalId: string

  // Optional url filter search parameter. Should be the same as the filter search parameters on a dashboard url.
  // Example: f--inventory_items.cost=%7B"kind"%3A"EQUALS"%2C"type"%3A"number"%2C"values"%3A%5B%5D%7D
  filterSearchParam?: string

  /*
   * Optional groups array property. The array should be a list of group names from the Omni application, which the embed user will be added to.
   */
  groups?: string[]

  /**
   * Used to set the host of signed embed URL, required when using vanity domains.
   * Protocol is not required, as https is assumed.
   * Port is not accepted. If required, use the `port` prop.
   *
   * @throws Error if `organizationName` is provided.
   * @example "omni.example.com"
   * @example "omni.another-example.app"
   */
  host?: string

  // Optional link access setting to control link security on embedded content. Note that regardless of the linkAccess value,
  // all non-Omni dashboard links will be shown and allowed in drill menus. Acceptable values include:
  // "__omni_link_access_open": Special string keyword that permisses and shows all Omni dashboard links on the embedded dashboard.
  // "abcd1234,efgh5678,ijkl9999": An allowlist of dashboard IDs that permisses and shows links to the specified dashboards.
  // undefined: If left undefined, the default behavior is to hide and disallow all links to other Omni dashboards on the embedded dashboard.
  linkAccess?: string

  /**
   * Optional mode setting that determines whether the entire application should be embedded or a single piece of content.
   *
   * APPLICATION: the entire application will be embedded, meaning in-app navigation and document header options will be available.
   * SINGLE_CONTENT: only the content specified in the contentId will be embedded and application mode features will be hidden.
   */
  mode?: EmbedSessionMode

  /**
   * Optional object that determines the model permissions for the embed user.
   * Keys are model ids. Values should be model roles — a base role or a custom
   * role name.
   */
  modelRoles?: Record<string, string>

  // Required name of the external user.
  name: string

  /**
   * Name of the organization the content belongs to. If provided, generates a default embed host
   * URL in the form of `https://<organizationName>.embed-omniapp.co`.
   *
   * @throws Error if `host` is provided.
   */
  organizationName?: string

  // Port of host.
  port?: number

  // Optional dark mode setting. Can be one of "true", "false", or "system".
  prefersDark?: string

  /**
   * When true, an existing content role for the embed user on the entity folder will not be overwritten
   * by the `entityFolderContentRole` value. If a content role does not exist on the entity folder for the embed user,
   * the `entityFolderContentRole` value will be applied.
   */
  preserveEntityFolderContentRole?: boolean

  // Signing secret available to Omni admins.
  secret: string

  // Optional theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
  theme?: string

  /**
   * Optional IANA timezone for the embed session (eg "America/New_York"). Unsupported values
   * are silently dropped by the Omni server and the login still succeeds. This does not update
   * the embed user's `omni_user_timezone` attribute — use `userAttributes` for that.
   */
  timezone?: string

  // Optional UI settings object to control appearance of embed experience.
  uiSettings?: EmbedUiSettingsObject

  /**
   * Optional user attributes to be passed to user associated with the
   * externalId. User attributes must be created in Omni before being
   * defined and given a value here.
   */
  userAttributes?: Record<string, string | string[] | number | number[]>
}

embedSsoContentDiscovery

This is the type signature for the embedSsoContentDiscovery function:

type EmbedSsoContentDiscoveryProps = {
  /**
   * Optional branch setting that sets the model branch of the embed session.
   */
  branch?: string

  /**
   * Optional object that determines the connection permissions for the embed user.
   * Keys are connection ids. Values should be connection roles — either an
   * `EmbedConnectionRoles` value or a custom role name.
   */
  connectionRoles?: Record<string, string>

  /**
   * Optional custom theme object. Note that this theme will only apply to dashboards viewed
   * during the generated embed session.
   */
  customTheme?: CustomThemeProperties

  /**
   * Optional custom theme ID setting. Note that this theme will only apply to dashboards viewed
   * during the generated embed session.
   */
  customThemeId?: string

  // Optional email parameter that sets the default scheduling email for the embed user.
  email?: string

  /**
   * Optional identifier to associate the user with an external organization or system.
   * Note that each distinct entity will generate its own folder and group. These can be used by
   * an embed user to share content with other members in the same entity.
   */
  entity?: string

  /**
   * Optional AI credit limit applied to the entity group corresponding to the `entity` value. Sets the
   * entity group's AI credit cap at login time and requires `entity` to be set. A number caps the entity
   * group's AI credit usage; the string "unlimited" is an explicit no-cap override; omitting it removes
   * any existing override so the entity group falls back to the organization default.
   */
  entityAiCreditLimit?: number | 'unlimited'

  /**
   * Sets embed user content permission on the entity folder. Can be one of "MANAGER", "EDITOR", "VIEWER",
   * or "NO_ACCESS".
   *
   * MANAGER: the user will have the ability to manage content and content permissions of the entity folder.
   * EDITOR: the user will have the ability to manage content in the entity folder.
   * VIEWER: the user will only be able to view content in the entity folder.
   * NO_ACCESS: the user will have no access to content in the top-level entity folder. Note that the
   *  entityFolderGroupContentRole should also be set to NO_ACCESS in order to completely restrict access
   *  to the top-level entity folder.
   */
  entityFolderContentRole?: EmbedEntityFolderContentRoles

  /**
   * Sets embed entity group content permission on the entity folder. Can be one of "MANAGER", "EDITOR", "VIEWER",
   * or "NO_ACCESS".
   *
   * MANAGER: all users in the group will have the ability to manage content and content permissions of the entity folder.
   * EDITOR: all users in the group have the ability to manage content in the entity folder.
   * VIEWER: all users in the group are restricted to just view content in the entity folder.
   * NO_ACCESS: all users in the group will have no access to content in the top-level entity folder.
   */
  entityFolderGroupContentRole?: EmbedEntityFolderContentRoles

  /**
   * Optional setting that customizes the generated entity folder label. This only affects the
   * entity folder corresponding to the `entity` parameter value.
   */
  entityFolderLabel?: string

  /**
   * Optional setting that customizes the generated entity group label. This only affects the
   * entity group corresponding to the `entity` parameter value.
   */
  entityGroupLabel?: string

  // Required identifier to associate the external user with an
  // automatically generated internal Omni user.
  /**
   * Optional lifetime of the generated URL, in seconds from now. Defaults to
   * 24 hours; must be positive and at most 7 days (604800). Travels as an `exp`
   * inside the signed payload.
   *
   * Shorter is better: an unredeemed URL that leaks is a bearer credential
   * until it expires.
   */
  expiresIn?: number

  externalId: string

  // Optional url filter search parameter. Should be the same as the filter search parameters on a dashboard url.
  // Example: f--inventory_items.cost=%7B"kind"%3A"EQUALS"%2C"type"%3A"number"%2C"values"%3A%5B%5D%7D
  filterSearchParam?: string

  /*
   * Optional groups array property. The array should be a list of group names from the Omni application, which the embed user will be added to.
   */
  groups?: string[]

  /**
   * Used to set the host of signed embed URL, required when using vanity domains.
   * Protocol is not required, as https is assumed.
   * Port is not accepted. If required, use the `port` prop.
   *
   * @throws Error if `organizationName` is provided.
   * @example "omni.example.com"
   * @example "omni.another-example.app"
   */
  host?: string

  // Optional link access setting to control link security on embedded content. Note that regardless of the linkAccess value,
  // all non-Omni dashboard links will be shown and allowed in drill menus. Acceptable values include:
  // "__omni_link_access_open": Special string keyword that permisses and shows all Omni dashboard links on the embedded dashboard.
  // "abcd1234,efgh5678,ijkl9999": An allowlist of dashboard IDs that permisses and shows links to the specified dashboards.
  // undefined: If left undefined, the default behavior is to hide and disallow all links to other Omni dashboards on the embedded dashboard.
  linkAccess?: string

  /**
   * Optional mode setting that determines whether the entire application should be embedded or a single piece of content.
   *
   * APPLICATION: the entire application will be embedded, meaning in-app navigation and document header options will be available.
   * SINGLE_CONTENT: only the content specified in the path will be embedded and application mode features will be hidden.
   */
  mode?: EmbedSessionMode

  /**
   * Optional object that determines the model permissions for the embed user.
   * Keys are model ids. Values should be model roles — a base role or a custom
   * role name.
   */
  modelRoles?: Record<string, string>

  // Required name of the external user.
  name: string

  /**
   * Name of the organization the content belongs to. If provided, generates a default embed host
   * URL in the form of `https://<organizationName>.embed-omniapp.co`.
   *
   * @throws Error if `host` is provided.
   */
  organizationName?: string

  /**
   * Required path property. The path value determines the starting content discovery page
   * for the generated embed session. Can be one of "my", "entity-folder", or "root".
   *
   * my: "My Content" page
   * entity-folder: embed entity folder
   * root: "Hub" page
   */
  path: string

  // Port of host.
  port?: number

  // Optional dark mode setting. Can be one of "true", "false", or "system".
  prefersDark?: string

  /**
   * When true, an existing content role for the embed user on the entity folder will not be overwritten
   * by the `entityFolderContentRole` value. If a content role does not exist on the entity folder for the embed user,
   * the `entityFolderContentRole` value will be applied.
   */
  preserveEntityFolderContentRole?: boolean

  // Signing secret available to Omni admins.
  secret: string

  // Optional theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
  theme?: string

  /**
   * Optional IANA timezone for the embed session (eg "America/New_York"). Unsupported values
   * are silently dropped by the Omni server and the login still succeeds. This does not update
   * the embed user's `omni_user_timezone` attribute — use `userAttributes` for that.
   */
  timezone?: string

  // Optional UI settings object to control appearance of embed experience.
  uiSettings?: EmbedUiSettingsObject

  /**
   * Optional user attributes to be passed to user associated with the
   * externalId. User attributes must be created in Omni before being
   * defined and given a value here.
   */
  userAttributes?: Record<string, string | string[] | number | number[]>
}

createSessionToken

This is the type signature for the createSessionToken function:

type CreateSessionTokenProps = {
  // Optional boolean property that toggles the dashboard's Access Boost setting.
  accessBoost?: boolean

  // An Omni API key used for authentication purposes. Can be generated in your Omni application in the Admin > API Keys section.
  apiKey: string

  /**
   * Optional object that determines the connection permissions for the embed user.
   * Keys are connection ids. Values should be connection roles — either an
   * `EmbedConnectionRoles` value or a custom role name.
   */
  connectionRoles?: Record<string, string>

  /**
   * Path of the content to embed, for example `/dashboards/abcd1234`.
   */
  contentPath: string

  // Optional custom theme object that styles the embedded dashboard.
  customTheme?: CustomThemeProperties

  /**
   * Optional custom theme ID setting that styles the embedded dashboard.
   * This ID should be from a theme created within the Omni application.
   */
  customThemeId?: string

  // Optional email parameter that sets the default scheduling email for the embed user.
  email?: string

  /**
   * Optional identifier to associate the user with an external organization or system.
   * Note that each distinct entity will generate its own folder and group. These can be used by
   * an embed user to share content with other members in the same entity.
   */
  entity?: string

  /**
   * Optional AI credit limit applied to the entity group corresponding to the `entity` value. Sets the
   * entity group's AI credit cap at login time and requires `entity` to be set. A number caps the entity
   * group's AI credit usage; the string "unlimited" is an explicit no-cap override; omitting it removes
   * any existing override so the entity group falls back to the organization default.
   */
  entityAiCreditLimit?: number | 'unlimited'

  /**
   * Sets embed user content permission on the entity folder. Can be one of "MANAGER", "EDITOR", "VIEWER",
   * or "NO_ACCESS".
   *
   * MANAGER: the user will have the ability to manage content and content permissions of the entity folder.
   * EDITOR: the user will have the ability to manage content in the entity folder.
   * VIEWER: the user will only be able to view content in the entity folder.
   * NO_ACCESS: the user will have no access to content in the top-level entity folder. Note that the
   *  entityFolderGroupContentRole should also be set to NO_ACCESS in order to completely restrict access
   *  to the top-level entity folder.
   */
  entityFolderContentRole?: EmbedEntityFolderContentRoles

  /**
   * Sets embed entity group content permission on the entity folder. Can be one of "MANAGER", "EDITOR", "VIEWER",
   * or "NO_ACCESS".
   *
   * MANAGER: all users in the group will have the ability to manage content and content permissions of the entity folder.
   * EDITOR: all users in the group have the ability to manage content in the entity folder.
   * VIEWER: all users in the group are restricted to just view content in the entity folder.
   * NO_ACCESS: all users in the group will have no access to content in the top-level entity folder.
   */
  entityFolderGroupContentRole?: EmbedEntityFolderContentRoles

  /**
   * Optional setting that customizes the generated entity folder label. This only affects the
   * entity folder corresponding to the `entity` parameter value.
   */
  entityFolderLabel?: string

  /**
   * Optional setting that customizes the generated entity group label. This only affects the
   * entity group corresponding to the `entity` parameter value.
   */
  entityGroupLabel?: string

  // Required identifier to associate the external user with an automatically generated internal Omni user.
  externalId: string

  /**
   * Optional url filter search parameter. Should be the same as the filter search parameters on a dashboard url.
   * Example: f--inventory_items.cost=%7B"kind"%3A"EQUALS"%2C"type"%3A"number"%2C"values"%3A%5B%5D%2C"is_negative"%3Afalse%2C"is_inclusive"%3Afalse%7D&f--users.state=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B"Aberdeen"%2C"Alabama"%5D%2C"is_negative"%3Afalse%7D&f--users.country=%7B"kind"%3A"EQUALS"%2C"type"%3A"string"%2C"values"%3A%5B"UK"%5D%2C"is_negative"%3Afalse%7D
   *
   */
  filterSearchParam?: string

  /*
   * Optional groups array property. The array should be a list of group names from the Omni application, which the embed user will be added to.
   */
  groups?: string[]

  /**
   * Used to set the host of signed embed URL, required when using vanity domains.
   * Protocol is not required, as https is assumed.
   * Port is not accepted. If required, use the `port` prop.
   *
   * @throws Error if `organizationName` is provided.
   * @example "omni.example.com"
   * @example "omni.another-example.app"
   */
  host?: string

  /**
   * Optional link access setting to control which Omni dashboard links are shown. Note that regardless of the linkAccess value,
   * all non-Omni dashboard links will be shown and allowed in drill menus. Acceptable values include:
   *
   * "__omni_link_access_open": Special string keyword that permisses and shows all Omni dashboard links on the embedded dashboard.
   * "abcd1234,efgh5678,ijkl9999": An allowlist of dashboard IDs that permisses and shows links to the specified dashboards.
   * undefined: If left undefined, the default behavior is to hide and disallow all links to other Omni dashboards on the embedded dashboard.
   */
  linkAccess?: string

  /**
   * Optional mode setting that determines whether the entire application should be embedded or a single piece of content.
   *
   * APPLICATION: the entire application will be embedded, meaning in-app navigation and document header options will be available.
   * SINGLE_CONTENT: only the content specified in the contentPath will be embedded and application mode features will be hidden.
   */
  mode?: EmbedSessionMode

  /**
   * Optional object that determines the model permissions for the embed user.
   * Keys are model ids. Values should be model roles — a base role or a custom
   * role name.
   */
  modelRoles?: Record<string, string>

  // Required name of the external user.
  name: string

  /**
   * Name of the organization the content belongs to. If provided, generates a default embed host
   * URL in the form of `https://<organizationName>.embed-omniapp.co`.
   *
   * @throws Error if `host` is provided.
   */
  organizationName?: string

  // Port of host.
  port?: number

  /**
   * When true, an existing content role for the embed user on the entity folder will not be overwritten
   * by the `entityFolderContentRole` value. If a content role does not exist on the entity folder for the embed user,
   * the `entityFolderContentRole` value will be applied.
   */
  preserveEntityFolderContentRole?: boolean

  /**
   * Optional IANA timezone for the embed session (eg "America/New_York"). Unsupported values
   * are silently dropped by the Omni server and the login still succeeds. This does not update
   * the embed user's `omni_user_timezone` attribute — use `userAttributes` for that.
   */
  timezone?: string

  // Optional UI settings object to control appearance of embed experience.
  uiSettings?: EmbedUiSettingsObject

  /**
   * Optional user attributes to be passed to user associated with the
   * externalId. User attributes must be created in Omni before being
   * defined and given a value here.
   */
  userAttributes?: Record<string, string | string[] | number | number[]>
}

redeemSessionToken

This is the type signature for the redeemSessionToken function:

type RedeemSessionTokenProps = {
  /**
   * Optional branch setting that sets the model branch of the embed session.
   */
  branch?: string

  /**
   * Used to set the host of signed embed URL, required when using vanity domains.
   * Protocol is not required, as https is assumed.
   * Port is not accepted. If required, use the `port` prop.
   *
   * @throws Error if `organizationName` is provided.
   * @example "omni.example.com"
   * @example "omni.another-example.app"
   */
  host?: string

  /**
   * Name of the organization the content belongs to. If provided, generates a default embed host
   * URL in the form of `https://<organizationName>.embed-omniapp.co`.
   *
   * @throws Error if `host` is provided.
   */
  organizationName?: string

  // Port of host.
  port?: number

  // Optional dark mode setting. Can be one of "true", "false", or "system".
  prefersDark?: string

  // Signing secret available to Omni admins.
  secret: string

  // Session token string. The `createSessionToken` sdk function returns a session token that
  // can be used as the `sessionToken` parameter here in `redeemSessionToken`.
  sessionToken: string

  // Optional theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
  theme?: string
}

uiSettings

uiSettings controls chrome in the embedded experience. Every key is optional, and every element shows by default.

type EmbedUiSettingsObject = {
  // When false, hides the top header bar on both dashboard and application pages.
  showHeader?: boolean

  // When false, hides all in-app navigation elements. In-app navigation is only
  // visible when the embed session is in APPLICATION mode.
  showNavigation?: boolean

  /**
   * When false, hides the chart context menu (the per-tile "..." / right-click menu)
   * on advanced-layout dashboards. The menu is hidden in view mode but kept in
   * draft/edit mode so authors can still edit tiles.
   */
  dashboardChartContextMenu?: boolean

  /**
   * Controls the folder-path breadcrumb in the document title header when in
   * APPLICATION mode. One of "display", "link" or "none". Defaults to "link".
   */
  documentBreadcrumb?: BreadcrumbDisplayMode

  // When false, hides the `Generated <timestamp>` stamp in the dashboard footer.
  dashboardGeneratedAt?: boolean

  // When false, hides the "Query ran <timestamp>" entry in a dashboard tile's menu.
  tileRanTimestamp?: boolean
}

The EmbedUiSettings enum exports the same keys if you would rather not write them as string literals:

import { EmbedUiSettings, embedSsoDashboard } from '@omni-co/embed'

const iframeUrl = await embedSsoDashboard({
  contentId: 'miU0hL6z',
  externalId: 'wile.e@coyote.co',
  name: 'Wile E',
  organizationName: 'acme',
  secret: 'abcdefghijklmnopqrstuvwxyz123456',
  uiSettings: {
    [EmbedUiSettings.SHOW_HEADER]: false,
    [EmbedUiSettings.SHOW_NAVIGATION]: false,
  },
})