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.
npm:
npm install @omni-co/embed
yarn:
yarn add @omni-co/embed
import {
embedSsoDashboard,
embedSsoWorkbook,
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",
});
// 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",
});// 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} />// Use `host` to create a link to a vanity domain.
// Note: `organizationName` and `domain` are incompatible with `host`
const iframeUrl = await embedSsoDashboard({
contentId: "miU0hL6z",
externalId: "wile.e@coyote.co",
host: "omni.example.com",
name: "Wile E",
secret: "abcdefghijklmnopqrstuvwxyz123456",
});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 object that determines the connection permissions for the embed user.
connectionRoles?: Record<string, EmbedConnectionRoles>;
// 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 content role setting for the entity folder. Can be one of "MANAGER", "EDITOR", or "VIEWER".
*
* 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.
*/
entityFolderContentRole?: EmbedEntityFolderContentRoles;
// 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 `domain` or `organizationName` are 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;
// 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;
// Signing secret available to Omni admins.
secret: string;
// Optional theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
theme?: string;
// Optional UI settings object to control appearance of embed experience.
uiSettings?: Record<EmbedUiSettings, boolean>;
/**
* 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[]>;
// DEPRECATED
/**
* @deprecated Introduced for internal testing only. For vanity domains, use the `host`
* prop instead. Will be dropped in a v1.0.0 release.
*
* @throws Error if `host` is provided.
*/
domain?: string;
};This is the type signature for the embedSsoWorkbook function:
type EmbedSsoWorkbookProps = {
// Optional object that determines the connection permissions for the embed user.
connectionRoles?: Record<string, EmbedConnectionRoles>;
/**
* 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 content role setting for the entity folder. Can be one of "MANAGER", "EDITOR", or "VIEWER".
*
* 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.
*/
entityFolderContentRole?: EmbedEntityFolderContentRoles;
// Required identifier to associate the external user with an
// automatically generated internal Omni user.
externalId: 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 `domain` or `organizationName` are provided.
* @example "omni.example.com"
* @example "omni.another-example.app"
*/
host?: 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;
// 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;
// Signing secret available to Omni admins.
secret: string;
// Optional theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
theme?: string;
// Optional UI settings object to control appearance of embed experience.
uiSettings?: Record<EmbedUiSettings, boolean>;
/**
* 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[]>;
// DEPRECATED
/**
* @deprecated Introduced for internal testing only. For vanity domains, use the `host`
* prop instead. Will be dropped in a v1.0.0 release.
*
* @throws Error if `host` is provided.
*/
domain?: string;
};This is the type signature for the embedSsoContentDiscovery function:
type EmbedSsoContentDiscoveryProps = {
// Optional object that determines the connection permissions for the embed user.
connectionRoles?: Record<string, EmbedConnectionRoles>;
/**
* 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 content role setting for the entity folder. Can be one of "MANAGER", "EDITOR", or "VIEWER".
*
* 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.
*/
entityFolderContentRole?: EmbedEntityFolderContentRoles;
// Required identifier to associate the external user with an
// automatically generated internal Omni user.
externalId: 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 `domain` or `organizationName` are provided.
* @example "omni.example.com"
* @example "omni.another-example.app"
*/
host?: 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;
// 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: EmbedSsoContentDiscoveryPath;
// 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;
// Optional theme setting. Can be one of "dawn", "vibes", "breeze" or "blank".
theme?: string;
// Optional UI settings object to control appearance of embed experience.
uiSettings?: Record<EmbedUiSettings, boolean>;
/**
* 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[]>;
// DEPRECATED
/**
* @deprecated Introduced for internal testing only. For vanity domains, use the `host`
* prop instead. Will be dropped in a v1.0.0 release.
*
* @throws Error if `host` is provided.
*/
domain?: string;
};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.
connectionRoles?: Record<string, EmbedConnectionRoles>;
// 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 content role setting for the entity folder. Can be one of "MANAGER", "EDITOR", or "VIEWER".
*
* 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.
*/
entityFolderContentRole?: EmbedEntityFolderContentRoles;
// 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 `domain` or `organizationName` are 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;
// 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 UI settings object to control appearance of embed experience.
uiSettings?: Record<EmbedUiSettings, boolean>;
/**
* 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[]>;
// DEPRECATED
/**
* @deprecated Introduced for internal testing only. For vanity domains, use the `host`
* prop instead. Will be dropped in a v1.0.0 release.
*
* @throws Error if `host` is provided.
*/
domain?: string;
};This is the type signature for the redeemSessionToken function:
type RedeemSessionTokenProps = {
/**
* 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 `domain` or `organizationName` are 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;
// DEPRECATED
/**
* @deprecated Introduced for internal testing only. For vanity domains, use the `host`
* prop instead. Will be dropped in a v1.0.0 release.
*
* @throws Error if `host` is provided.
*/
domain?: string;
};