**This SDK is intented to be used in a server context.**
npm install @omni-co/embedThis 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
`ts
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",
});
`
`ts
// Step 1
const { success, sessionToken } = await createSessionToken({
apiKey: "
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: "
sessionToken,
});
...
`
`tshost
// Use to create a link to a vanity domain.organizationName
// Note: 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:
`ts
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
// 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;
/**
* 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;
// 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.domain
*
* @throws Error if 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;
// Optional object that determines the model permissions for the embed user.
modelRoles?: Record
// 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://.host
*
* @throws Error if 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,entityFolderContentRole
* the 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 UI settings object to control appearance of embed experience.
uiSettings?: Record
/**
* 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
// 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 is provided.`
*/
domain?: string;
};
This is the type signature for the embedSsoWorkbook function:
`ts
type EmbedSsoWorkbookProps = {
// Optional object that determines the connection permissions for the embed user.
connectionRoles?: Record
/**
* 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;
/**
* 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;
// 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.domain
*
* @throws Error if 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;
// Optional object that determines the model permissions for the embed user.
modelRoles?: Record
// 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://.host
*
* @throws Error if 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,entityFolderContentRole
* the 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 UI settings object to control appearance of embed experience.
uiSettings?: Record
/**
* 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
// 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 is provided.`
*/
domain?: string;
};
This is the type signature for the embedSsoContentDiscovery function:
`ts
type EmbedSsoContentDiscoveryProps = {
// Optional object that determines the connection permissions for the embed user.
connectionRoles?: Record
/**
* 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;
/**
* 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;
// 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.domain
*
* @throws Error if 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;
// Optional object that determines the model permissions for the embed user.
modelRoles?: Record
// 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://.host
*
* @throws Error if 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;
/**
* 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,entityFolderContentRole
* the 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 UI settings object to control appearance of embed experience.
uiSettings?: Record
/**
* 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
// 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 is provided.`
*/
domain?: string;
};
This is the type signature for the createSessionToken function:
`ts
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
// 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;
/**
* 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;
// 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.domain
*
* @throws Error if 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;
// Optional object that determines the model permissions for the embed user.
modelRoles?: Record
// 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://.host
*
* @throws Error if 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,entityFolderContentRole
* the value will be applied.
*/
preserveEntityFolderContentRole?: boolean;
// Optional UI settings object to control appearance of embed experience.
uiSettings?: Record
/**
* 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
// 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 is provided.`
*/
domain?: string;
};
This is the type signature for the redeemSessionToken function:
`tsport
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 prop.domain
*
* @throws Error if 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://.host
*
* @throws Error if 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 thatsessionToken
// can be used as the 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 is provided.``
*/
domain?: string;
};