omni.OmniEmbedder

Factory class for building and signing embedding URLs.

Parameters:

Name	Type	Description	Default
organization_name	str | None	organization_name: Omni organization name. OMNI_ORGANIZATION_NAME environment variable will be used as a fallback.	None
embed_secret	str | None	Omni embed secret. OMNI_EMBED_SECRET environment variable will be used as a fallback.	None
vanity_domain	str | None	Vanity domain configured with Omni. Should not be fully qualified. OMNI_VANITY_DOMAIN environment variable will be used as a fallback.	None

Attributes:

Name	Type	Description
embed_login_url		Base url of embedding urls.
embed_secret		Omni embed secret.

Source code in src/omni/embed.py

class OmniEmbedder:
    """Factory class for building and signing embedding URLs.

    Args:
        organization_name: organization_name: Omni organization name. OMNI_ORGANIZATION_NAME environment variable will
            be used as a fallback.
        embed_secret: Omni embed secret. OMNI_EMBED_SECRET environment variable will be used as a fallback.
        vanity_domain: Vanity domain configured with Omni. Should not be fully qualified. OMNI_VANITY_DOMAIN
            environment variable will be used as a fallback.

    Attributes:
        embed_login_url: Base url of embedding urls.
        embed_secret: Omni embed secret.
    """

    class AccessMode(Enum):
        """AccessMode options

        Attributes:
            application: APPLICATION
            single_content: SINGLE_CONTENT
        """

        application = "APPLICATION"
        single_content = "SINGLE_CONTENT"

    class ContentRole(Enum):
        """ContentRole options

        Attributes:
            viewer: VIEWER
            editor: EDITOR
            manager: MANAGER
            no_access: NO_ACCESS
        """

        viewer = "VIEWER"
        editor = "EDITOR"
        manager = "MANAGER"
        no_access = "NO_ACCESS"

    class PrefersDark(Enum):
        """PrefersDark options

        Attributes:
            yes: true
            no: false
            system: system
        """

        yes = "true"
        no = "false"
        system = "system"

    class Theme(Enum):
        """Theme options

        Attributes:
            dawn: dawn
            vibes: vibes
            breeze: breeze
            blank: blank
        """

        dawn = "dawn"
        vibes = "vibes"
        breeze = "breeze"
        blank = "blank"

    def __init__(
        self,
        organization_name: str | None = None,
        embed_secret: str | None = None,
        vanity_domain: str | None = None,
    ):
        omni_config = OmniConfig(
            required_attrs=["embed_secret"],
            organization_name=organization_name,
            embed_secret=embed_secret,
            vanity_domain=vanity_domain,
        )
        if not omni_config.vanity_domain and not omni_config.organization_name:
            raise OmniConfigError(
                "You must pass the vanity_domain or organization_name arguments OR "
                "set the OMNI_ORGANIZATION_NAME or OMNI_VANITY_DOMAIN environment variables."
            )
        embed_host = (
            omni_config.vanity_domain
            or f"{omni_config.organization_name}.embed-omniapp.co"
        )
        self.embed_login_url = f"https://{embed_host}/embed/login"

        # Required to appease mypy. If embed_secret is missing an OmniConfigError will have already been raised by the OmniConfig class.
        assert omni_config.embed_secret

        self.embed_secret = omni_config.embed_secret

    def build_dashboard_url(
        self,
        content_id: str,
        external_id: str,
        name: str,
        page_key: str | None = None,
        **options: Any,
    ) -> str:
        """Builds a signed embedding URL for a dashboard.

        Args:
            content_id: ID of the dashboard to embed, e.g. "da24491e".
            external_id: Unique ID for the embed user.
            name: Name for the embed user's name property.
            page_key: Key of the page to open on a multi-page dashboard, e.g. "revenue". Omitting it
                opens the dashboard's first page.
            **options: Any of the optional keyword arguments accepted by
                [build_url][omni.OmniEmbedder.build_url].

        Returns:
            str: Signed embedding URL.

        Raises:
            ValueError: If page_key is empty or is one of Omni's reserved system values.
        """
        content_path = self._content_path("dashboards", content_id)
        if page_key is not None:
            content_path = f"{content_path}/{self._validate_page_key(page_key)}"
        return self.build_url(
            content_path=content_path,
            external_id=external_id,
            name=name,
            **options,
        )

    def build_workbook_url(
        self,
        content_id: str,
        external_id: str,
        name: str,
        **options: Any,
    ) -> str:
        """Builds a signed embedding URL for a workbook.

        Args:
            content_id: ID of the workbook to embed, e.g. "da24491e".
            external_id: Unique ID for the embed user.
            name: Name for the embed user's name property.
            **options: Any of the optional keyword arguments accepted by
                [build_url][omni.OmniEmbedder.build_url].

        Returns:
            str: Signed embedding URL.
        """
        return self.build_url(
            content_path=self._content_path("w", content_id),
            external_id=external_id,
            name=name,
            **options,
        )

    def build_app_url(
        self,
        content_id: str,
        external_id: str,
        name: str,
        **options: Any,
    ) -> str:
        """Builds a signed embedding URL for an app.

        Args:
            content_id: ID of the app to embed, e.g. "da24491e".
            external_id: Unique ID for the embed user.
            name: Name for the embed user's name property.
            **options: Any of the optional keyword arguments accepted by
                [build_url][omni.OmniEmbedder.build_url].

        Returns:
            str: Signed embedding URL.
        """
        return self.build_url(
            content_path=self._content_path("apps", content_id),
            external_id=external_id,
            name=name,
            **options,
        )

    def build_chat_url(
        self,
        external_id: str,
        name: str,
        **options: Any,
    ) -> str:
        """Builds a signed embedding URL for chat. Chat has no content ID - it always lives at "/chat".

        Args:
            external_id: Unique ID for the embed user.
            name: Name for the embed user's name property.
            **options: Any of the optional keyword arguments accepted by
                [build_url][omni.OmniEmbedder.build_url].

        Returns:
            str: Signed embedding URL.
        """
        return self.build_url(
            content_path="/chat",
            external_id=external_id,
            name=name,
            **options,
        )

    @staticmethod
    def _validate_page_key(page_key: str) -> str:
        """Validates a dashboard page key against Omni's rules, returning it unchanged."""
        if not page_key:
            raise ValueError("page_key must not be empty.")
        if page_key.lower() in RESERVED_PAGE_KEYS:
            raise ValueError(
                f"page_key '{page_key}' is one of Omni's reserved system values: "
                f"{', '.join(sorted(RESERVED_PAGE_KEYS))}."
            )
        return page_key

    @staticmethod
    def _content_path(prefix: str, content_id: str) -> str:
        """Builds a content path from a bare content ID, rejecting anything that looks like a full path."""
        if not content_id or "/" in content_id:
            raise ValueError(
                "content_id must be a bare content ID, e.g. 'da24491e'. Pass a full content path to "
                "build_url instead."
            )
        return f"/{prefix}/{content_id}"

    def build_url(
        self,
        content_path: str,
        external_id: str,
        name: str,
        *,
        access_boost: bool | None = None,
        connection_roles: dict | None = None,
        custom_theme: dict | None = None,
        custom_theme_id: str | None = None,
        email: str | None = None,
        entity: str | None = None,
        entity_folder_content_role: ContentRole | None = None,
        entity_folder_group_content_role: ContentRole | None = None,
        entity_folder_label: str | None = None,
        entity_group_label: str | None = None,
        expires_in: int | None = None,
        filter_search_params: str | dict | None = None,
        groups: list[str] | None = None,
        link_access: bool | list[str] | None = None,
        mode: AccessMode | None = None,
        model_roles: dict | None = None,
        prefers_dark: PrefersDark | None = None,
        preserve_entity_folder_content_role: bool | None = None,
        signing_version: SigningVersion = "v1",
        theme: Theme | None = None,
        ui_settings: dict | None = None,
        user_attributes: dict | None = None,
    ) -> str:
        """
        Builds a signed dashboard embedding URL. For more information on the options see the Omni Docs:
        https://docs.omni.co/embed/setup/url-parameters

        Args:
            access_boost (bool, optional): Enables AccessBoost for the embedded dashboard.
            connection_roles (dict, optional): Level of access for all models in a connection.
            content_path (str): Path pointing to the dashboard you wish to embed.
            custom_theme (dict, optional): Custom theme properties for styling embedded dashboards.
            custom_theme_id (str, optional): Theme ID from your Omni instance to stylize embedded dashboards.
            email (str, optional): Email for entity users when sharing content or sending deliveries.
            entity (str, optional): User group identifier to associate the embed user with a larger group.
            entity_folder_content_role (str, optional): Content role for the embed user's shared entity folder.
            entity_folder_group_content_role (str, optional): Content role for the embed entity group shared folder.
            entity_folder_label (str, optional): Label for the embed user's associated entity folder.
            entity_group_label (str, optional): Label for the embed user's associated entity group.
            expires_in (int, optional): Lifetime of the URL in seconds. Must be positive and no more than 7 days
                (604800 seconds). Defaults to 24 hours. Only used by the v1 signing format; ignored for v0, which
                has nowhere to carry an expiry.
            external_id (str): Unique ID for the embed user.
            filter_search_params (str | dict, optional): Filters to apply for the embedded content.
            groups (list[str], optional): Associate embed user with existing user groups in your Omni instance.
            link_access (bool | list[str], optional): Controls which Omni dashboards can be linked to from the embedded dashboard.
            mode (AccessMode, optional): Type of access users will have to Omni in the iframe.
            model_roles (dict, optional): Level of access for individual models in a connection.
            name (str): Name for the embed user's name property.
            prefers_dark (PrefersDark, optional): Light or dark mode appearance.
            preserve_entity_folder_content_role (bool, optional): Retains the embed user's existing entity folder content role.
            signing_version (str, optional): Signing format to use - "v1" (default) or "v0" (legacy). The v0 format is
                unsupported by Omni after October 1, 2026 and removed by January 1, 2027.
            theme (Theme, optional): Built-in Omni application theme.
            ui_settings (dict, optional): General settings of the application in embed.
            user_attributes (dict, optional): User attributes to apply to the embed user.

        Returns:
            str: Signed dashboard embedding URL.

        Raises:
            ValueError: If an argument is invalid or the generated v1 payload is too large.
        """

        if signing_version not in ("v0", "v1"):
            raise ValueError('signing_version must be either "v1" or "v0".')

        # Preprocess some values before passing to URL object.
        if link_access is True:
            _link_access = "__omni_link_access_open"
        elif isinstance(link_access, list):
            _link_access = ",".join(link_access)
        elif not link_access:
            _link_access = None
        else:
            raise ValueError(
                "link_access must be a list of dashboard IDs or True to allow links to all dashboards."
            )

        # Convert empty dicts and strings to None.
        filter_search_params = filter_search_params or None
        if isinstance(filter_search_params, dict):
            filter_search_params = urllib.parse.urlencode(
                filter_search_params, doseq=True
            )

        nonce = uuid.uuid4().hex

        if signing_version == "v1":
            # In v1 the parameters are carried as real JSON inside a single signed payload, so JSON-valued
            # parameters are passed through as objects and arrays rather than pre-stringified strings.
            v1_params: dict[str, Any] = {
                "loginUrl": self.embed_login_url,
                "contentPath": content_path,
                "externalId": external_id,
                "name": name,
                "nonce": nonce,
                "accessBoost": True if access_boost else None,
                "connectionRoles": connection_roles or None,
                "customTheme": custom_theme or None,
                "customThemeId": custom_theme_id,
                "email": email,
                "entity": entity,
                "entityFolderContentRole": (
                    entity_folder_content_role.value
                    if entity_folder_content_role
                    else None
                ),
                "entityFolderGroupContentRole": (
                    entity_folder_group_content_role.value
                    if entity_folder_group_content_role
                    else None
                ),
                "entityFolderLabel": entity_folder_label,
                "entityGroupLabel": entity_group_label,
                "filterSearchParam": filter_search_params,
                "groups": groups or None,
                "linkAccess": _link_access,
                "mode": mode.value if mode else None,
                "modelRoles": model_roles or None,
                "prefersDark": prefers_dark.value if prefers_dark else None,
                "preserveEntityFolderContentRole": (
                    True if preserve_entity_folder_content_role else None
                ),
                "theme": theme.value if theme else None,
                "uiSettings": ui_settings or None,
                "userAttributes": user_attributes or None,
            }
            return self._build_v1_url(v1_params, expires_in)

        url = EmbedUrl(
            base_url=self.embed_login_url,
            contentPath=content_path,
            externalId=external_id,
            name=name,
            accessBoost="true" if access_boost else None,
            connectionRoles=(
                compact_json_dump(connection_roles) if connection_roles else None
            ),
            customTheme=compact_json_dump(custom_theme) if custom_theme else None,
            customThemeId=custom_theme_id,
            email=email,
            entity=entity,
            entityFolderContentRole=(
                entity_folder_content_role.value if entity_folder_content_role else None
            ),
            entityFolderGroupContentRole=(
                entity_folder_group_content_role.value
                if entity_folder_group_content_role
                else None
            ),
            entityFolderLabel=entity_folder_label,
            entityGroupLabel=entity_group_label,
            filterSearchParam=filter_search_params,
            groups=compact_json_dump(groups) if groups else None,
            linkAccess=_link_access,
            mode=mode.value if mode else None,
            modelRoles=compact_json_dump(model_roles) if model_roles else None,
            prefersDark=prefers_dark.value if prefers_dark else None,
            preserveEntityFolderContentRole=(
                "true" if preserve_entity_folder_content_role else None
            ),
            theme=theme.value if theme else None,
            uiSettings=compact_json_dump(ui_settings) if ui_settings else None,
            userAttributes=(
                compact_json_dump(user_attributes) if user_attributes else None
            ),
            nonce=nonce,
        )

        self._sign_url(url)
        return str(url)

    def _build_v1_url(self, params: dict[str, Any], expires_in: int | None) -> str:
        """Builds and signs a URL using the v1 signed payload format as documented here
        https://docs.omni.co/embed/setup/standard-sso/latest#manual-generation
        """

        if expires_in is None:
            expires_in = DEFAULT_EXPIRES_IN
        if expires_in <= 0 or expires_in > MAX_EXPIRES_IN:
            raise ValueError(
                f"expires_in must be a positive number of seconds no greater than {MAX_EXPIRES_IN} (7 days)."
            )

        payload_params = {
            key: value for key, value in params.items() if value is not None
        }

        # Absolute expiry in epoch seconds, following the JWT convention.
        payload_params["exp"] = int(time.time()) + expires_in

        # Raw DEFLATE (RFC 1951): a negative wbits omits the zlib wrapper.
        compressor = zlib.compressobj(9, zlib.DEFLATED, -zlib.MAX_WBITS)
        compressed = compressor.compress(
            json.dumps(payload_params, separators=(",", ":")).encode("utf-8")
        )
        compressed += compressor.flush()
        payload = base64.urlsafe_b64encode(compressed).decode("ascii")

        if len(payload) > MAX_PAYLOAD_SIZE:
            raise ValueError(
                f"The encoded payload is larger than the {MAX_PAYLOAD_SIZE} byte limit. This usually means a "
                "parameter, most often user_attributes, is carrying more than it should."
            )

        # The signature covers the base64url payload string itself, not the compressed bytes.
        hmac_hash = hmac.new(
            self.embed_secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256
        ).digest()
        signature = base64.urlsafe_b64encode(hmac_hash).decode("ascii")

        query = urllib.parse.urlencode({"payload": payload, "signature": signature})
        return f"{self.embed_login_url}?{query}"

    def _sign_url(self, url: EmbedUrl) -> None:
        """Creates a signature and adds it to the URL object."""

        # IMPORTANT: These must be in the correct order as documented here
        # https://docs.omni.co/embed/setup/standard-sso/v0-legacy#manual-generation

        blob_items = [
            url.base_url,
            url.contentPath,
            url.externalId,
            url.name,
            url.nonce,
            url.accessBoost,
            url.connectionRoles,
            url.customTheme,
            url.customThemeId,
            url.email,
            url.entity,
            url.entityFolderContentRole,
            url.entityFolderGroupContentRole,
            url.entityFolderLabel,
            url.entityGroupLabel,
            url.filterSearchParam,
            url.groups,
            url.linkAccess,
            url.mode,
            url.modelRoles,
            url.prefersDark,
            url.preserveEntityFolderContentRole,
            url.theme,
            url.uiSettings,
            url.userAttributes,
        ]
        blob = "\n".join([i for i in blob_items if i is not None])
        hmac_hash = hmac.new(
            self.embed_secret.encode("utf-8"), blob.encode("utf-8"), hashlib.sha256
        ).digest()
        url.signature = base64.urlsafe_b64encode(hmac_hash).decode("utf-8")

AccessMode

Bases: Enum

AccessMode options

Attributes:

Name	Type	Description
application		APPLICATION
single_content		SINGLE_CONTENT

Source code in src/omni/embed.py

class AccessMode(Enum):
    """AccessMode options

    Attributes:
        application: APPLICATION
        single_content: SINGLE_CONTENT
    """

    application = "APPLICATION"
    single_content = "SINGLE_CONTENT"

ContentRole

Bases: Enum

ContentRole options

Attributes:

Name	Type	Description
viewer		VIEWER
editor		EDITOR
manager		MANAGER
no_access		NO_ACCESS

Source code in src/omni/embed.py

class ContentRole(Enum):
    """ContentRole options

    Attributes:
        viewer: VIEWER
        editor: EDITOR
        manager: MANAGER
        no_access: NO_ACCESS
    """

    viewer = "VIEWER"
    editor = "EDITOR"
    manager = "MANAGER"
    no_access = "NO_ACCESS"

PrefersDark

Bases: Enum

PrefersDark options

Attributes:

Name	Type	Description
yes		true
no		false
system		system

Source code in src/omni/embed.py

class PrefersDark(Enum):
    """PrefersDark options

    Attributes:
        yes: true
        no: false
        system: system
    """

    yes = "true"
    no = "false"
    system = "system"

Theme

Bases: Enum

Theme options

Attributes:

Name	Type	Description
dawn		dawn
vibes		vibes
breeze		breeze
blank		blank

Source code in src/omni/embed.py

class Theme(Enum):
    """Theme options

    Attributes:
        dawn: dawn
        vibes: vibes
        breeze: breeze
        blank: blank
    """

    dawn = "dawn"
    vibes = "vibes"
    breeze = "breeze"
    blank = "blank"

build_app_url(content_id, external_id, name, **options)

Builds a signed embedding URL for an app.

Parameters:

Name	Type	Description	Default
content_id	str	ID of the app to embed, e.g. "da24491e".	required
external_id	str	Unique ID for the embed user.	required
name	str	Name for the embed user's name property.	required
**options	Any	Any of the optional keyword arguments accepted by build_url.	{}

Returns:

Name	Type	Description
str	str	Signed embedding URL.

Source code in src/omni/embed.py

def build_app_url(
    self,
    content_id: str,
    external_id: str,
    name: str,
    **options: Any,
) -> str:
    """Builds a signed embedding URL for an app.

    Args:
        content_id: ID of the app to embed, e.g. "da24491e".
        external_id: Unique ID for the embed user.
        name: Name for the embed user's name property.
        **options: Any of the optional keyword arguments accepted by
            [build_url][omni.OmniEmbedder.build_url].

    Returns:
        str: Signed embedding URL.
    """
    return self.build_url(
        content_path=self._content_path("apps", content_id),
        external_id=external_id,
        name=name,
        **options,
    )

build_chat_url(external_id, name, **options)

Builds a signed embedding URL for chat. Chat has no content ID - it always lives at "/chat".

Parameters:

Name	Type	Description	Default
external_id	str	Unique ID for the embed user.	required
name	str	Name for the embed user's name property.	required
**options	Any	Any of the optional keyword arguments accepted by build_url.	{}

Returns:

Name	Type	Description
str	str	Signed embedding URL.

Source code in src/omni/embed.py

def build_chat_url(
    self,
    external_id: str,
    name: str,
    **options: Any,
) -> str:
    """Builds a signed embedding URL for chat. Chat has no content ID - it always lives at "/chat".

    Args:
        external_id: Unique ID for the embed user.
        name: Name for the embed user's name property.
        **options: Any of the optional keyword arguments accepted by
            [build_url][omni.OmniEmbedder.build_url].

    Returns:
        str: Signed embedding URL.
    """
    return self.build_url(
        content_path="/chat",
        external_id=external_id,
        name=name,
        **options,
    )

build_dashboard_url(content_id, external_id, name, page_key=None, **options)

Builds a signed embedding URL for a dashboard.

Parameters:

Name	Type	Description	Default
content_id	str	ID of the dashboard to embed, e.g. "da24491e".	required
external_id	str	Unique ID for the embed user.	required
name	str	Name for the embed user's name property.	required
page_key	str | None	Key of the page to open on a multi-page dashboard, e.g. "revenue". Omitting it opens the dashboard's first page.	None
**options	Any	Any of the optional keyword arguments accepted by build_url.	{}

Returns:

Name	Type	Description
str	str	Signed embedding URL.

Raises:

Type	Description
ValueError	If page_key is empty or is one of Omni's reserved system values.

Source code in src/omni/embed.py

def build_dashboard_url(
    self,
    content_id: str,
    external_id: str,
    name: str,
    page_key: str | None = None,
    **options: Any,
) -> str:
    """Builds a signed embedding URL for a dashboard.

    Args:
        content_id: ID of the dashboard to embed, e.g. "da24491e".
        external_id: Unique ID for the embed user.
        name: Name for the embed user's name property.
        page_key: Key of the page to open on a multi-page dashboard, e.g. "revenue". Omitting it
            opens the dashboard's first page.
        **options: Any of the optional keyword arguments accepted by
            [build_url][omni.OmniEmbedder.build_url].

    Returns:
        str: Signed embedding URL.

    Raises:
        ValueError: If page_key is empty or is one of Omni's reserved system values.
    """
    content_path = self._content_path("dashboards", content_id)
    if page_key is not None:
        content_path = f"{content_path}/{self._validate_page_key(page_key)}"
    return self.build_url(
        content_path=content_path,
        external_id=external_id,
        name=name,
        **options,
    )

build_url(content_path, external_id, name, *, access_boost=None, connection_roles=None, custom_theme=None, custom_theme_id=None, email=None, entity=None, entity_folder_content_role=None, entity_folder_group_content_role=None, entity_folder_label=None, entity_group_label=None, expires_in=None, filter_search_params=None, groups=None, link_access=None, mode=None, model_roles=None, prefers_dark=None, preserve_entity_folder_content_role=None, signing_version='v1', theme=None, ui_settings=None, user_attributes=None)

Builds a signed dashboard embedding URL. For more information on the options see the Omni Docs: https://docs.omni.co/embed/setup/url-parameters

Parameters:

Name	Type	Description	Default
access_boost	bool	Enables AccessBoost for the embedded dashboard.	None
connection_roles	dict	Level of access for all models in a connection.	None
content_path	str	Path pointing to the dashboard you wish to embed.	required
custom_theme	dict	Custom theme properties for styling embedded dashboards.	None
custom_theme_id	str	Theme ID from your Omni instance to stylize embedded dashboards.	None
email	str	Email for entity users when sharing content or sending deliveries.	None
entity	str	User group identifier to associate the embed user with a larger group.	None
entity_folder_content_role	str	Content role for the embed user's shared entity folder.	None
entity_folder_group_content_role	str	Content role for the embed entity group shared folder.	None
entity_folder_label	str	Label for the embed user's associated entity folder.	None
entity_group_label	str	Label for the embed user's associated entity group.	None
expires_in	int	Lifetime of the URL in seconds. Must be positive and no more than 7 days (604800 seconds). Defaults to 24 hours. Only used by the v1 signing format; ignored for v0, which has nowhere to carry an expiry.	None
external_id	str	Unique ID for the embed user.	required
filter_search_params	str | dict	Filters to apply for the embedded content.	None
groups	list[str]	Associate embed user with existing user groups in your Omni instance.	None
link_access	bool | list[str]	Controls which Omni dashboards can be linked to from the embedded dashboard.	None
mode	AccessMode	Type of access users will have to Omni in the iframe.	None
model_roles	dict	Level of access for individual models in a connection.	None
name	str	Name for the embed user's name property.	required
prefers_dark	PrefersDark	Light or dark mode appearance.	None
preserve_entity_folder_content_role	bool	Retains the embed user's existing entity folder content role.	None
signing_version	str	Signing format to use - "v1" (default) or "v0" (legacy). The v0 format is unsupported by Omni after October 1, 2026 and removed by January 1, 2027.	'v1'
theme	Theme	Built-in Omni application theme.	None
ui_settings	dict	General settings of the application in embed.	None
user_attributes	dict	User attributes to apply to the embed user.	None

Returns:

Name	Type	Description
str	str	Signed dashboard embedding URL.

Raises:

Type	Description
ValueError	If an argument is invalid or the generated v1 payload is too large.

Source code in src/omni/embed.py

def build_url(
    self,
    content_path: str,
    external_id: str,
    name: str,
    *,
    access_boost: bool | None = None,
    connection_roles: dict | None = None,
    custom_theme: dict | None = None,
    custom_theme_id: str | None = None,
    email: str | None = None,
    entity: str | None = None,
    entity_folder_content_role: ContentRole | None = None,
    entity_folder_group_content_role: ContentRole | None = None,
    entity_folder_label: str | None = None,
    entity_group_label: str | None = None,
    expires_in: int | None = None,
    filter_search_params: str | dict | None = None,
    groups: list[str] | None = None,
    link_access: bool | list[str] | None = None,
    mode: AccessMode | None = None,
    model_roles: dict | None = None,
    prefers_dark: PrefersDark | None = None,
    preserve_entity_folder_content_role: bool | None = None,
    signing_version: SigningVersion = "v1",
    theme: Theme | None = None,
    ui_settings: dict | None = None,
    user_attributes: dict | None = None,
) -> str:
    """
    Builds a signed dashboard embedding URL. For more information on the options see the Omni Docs:
    https://docs.omni.co/embed/setup/url-parameters

    Args:
        access_boost (bool, optional): Enables AccessBoost for the embedded dashboard.
        connection_roles (dict, optional): Level of access for all models in a connection.
        content_path (str): Path pointing to the dashboard you wish to embed.
        custom_theme (dict, optional): Custom theme properties for styling embedded dashboards.
        custom_theme_id (str, optional): Theme ID from your Omni instance to stylize embedded dashboards.
        email (str, optional): Email for entity users when sharing content or sending deliveries.
        entity (str, optional): User group identifier to associate the embed user with a larger group.
        entity_folder_content_role (str, optional): Content role for the embed user's shared entity folder.
        entity_folder_group_content_role (str, optional): Content role for the embed entity group shared folder.
        entity_folder_label (str, optional): Label for the embed user's associated entity folder.
        entity_group_label (str, optional): Label for the embed user's associated entity group.
        expires_in (int, optional): Lifetime of the URL in seconds. Must be positive and no more than 7 days
            (604800 seconds). Defaults to 24 hours. Only used by the v1 signing format; ignored for v0, which
            has nowhere to carry an expiry.
        external_id (str): Unique ID for the embed user.
        filter_search_params (str | dict, optional): Filters to apply for the embedded content.
        groups (list[str], optional): Associate embed user with existing user groups in your Omni instance.
        link_access (bool | list[str], optional): Controls which Omni dashboards can be linked to from the embedded dashboard.
        mode (AccessMode, optional): Type of access users will have to Omni in the iframe.
        model_roles (dict, optional): Level of access for individual models in a connection.
        name (str): Name for the embed user's name property.
        prefers_dark (PrefersDark, optional): Light or dark mode appearance.
        preserve_entity_folder_content_role (bool, optional): Retains the embed user's existing entity folder content role.
        signing_version (str, optional): Signing format to use - "v1" (default) or "v0" (legacy). The v0 format is
            unsupported by Omni after October 1, 2026 and removed by January 1, 2027.
        theme (Theme, optional): Built-in Omni application theme.
        ui_settings (dict, optional): General settings of the application in embed.
        user_attributes (dict, optional): User attributes to apply to the embed user.

    Returns:
        str: Signed dashboard embedding URL.

    Raises:
        ValueError: If an argument is invalid or the generated v1 payload is too large.
    """

    if signing_version not in ("v0", "v1"):
        raise ValueError('signing_version must be either "v1" or "v0".')

    # Preprocess some values before passing to URL object.
    if link_access is True:
        _link_access = "__omni_link_access_open"
    elif isinstance(link_access, list):
        _link_access = ",".join(link_access)
    elif not link_access:
        _link_access = None
    else:
        raise ValueError(
            "link_access must be a list of dashboard IDs or True to allow links to all dashboards."
        )

    # Convert empty dicts and strings to None.
    filter_search_params = filter_search_params or None
    if isinstance(filter_search_params, dict):
        filter_search_params = urllib.parse.urlencode(
            filter_search_params, doseq=True
        )

    nonce = uuid.uuid4().hex

    if signing_version == "v1":
        # In v1 the parameters are carried as real JSON inside a single signed payload, so JSON-valued
        # parameters are passed through as objects and arrays rather than pre-stringified strings.
        v1_params: dict[str, Any] = {
            "loginUrl": self.embed_login_url,
            "contentPath": content_path,
            "externalId": external_id,
            "name": name,
            "nonce": nonce,
            "accessBoost": True if access_boost else None,
            "connectionRoles": connection_roles or None,
            "customTheme": custom_theme or None,
            "customThemeId": custom_theme_id,
            "email": email,
            "entity": entity,
            "entityFolderContentRole": (
                entity_folder_content_role.value
                if entity_folder_content_role
                else None
            ),
            "entityFolderGroupContentRole": (
                entity_folder_group_content_role.value
                if entity_folder_group_content_role
                else None
            ),
            "entityFolderLabel": entity_folder_label,
            "entityGroupLabel": entity_group_label,
            "filterSearchParam": filter_search_params,
            "groups": groups or None,
            "linkAccess": _link_access,
            "mode": mode.value if mode else None,
            "modelRoles": model_roles or None,
            "prefersDark": prefers_dark.value if prefers_dark else None,
            "preserveEntityFolderContentRole": (
                True if preserve_entity_folder_content_role else None
            ),
            "theme": theme.value if theme else None,
            "uiSettings": ui_settings or None,
            "userAttributes": user_attributes or None,
        }
        return self._build_v1_url(v1_params, expires_in)

    url = EmbedUrl(
        base_url=self.embed_login_url,
        contentPath=content_path,
        externalId=external_id,
        name=name,
        accessBoost="true" if access_boost else None,
        connectionRoles=(
            compact_json_dump(connection_roles) if connection_roles else None
        ),
        customTheme=compact_json_dump(custom_theme) if custom_theme else None,
        customThemeId=custom_theme_id,
        email=email,
        entity=entity,
        entityFolderContentRole=(
            entity_folder_content_role.value if entity_folder_content_role else None
        ),
        entityFolderGroupContentRole=(
            entity_folder_group_content_role.value
            if entity_folder_group_content_role
            else None
        ),
        entityFolderLabel=entity_folder_label,
        entityGroupLabel=entity_group_label,
        filterSearchParam=filter_search_params,
        groups=compact_json_dump(groups) if groups else None,
        linkAccess=_link_access,
        mode=mode.value if mode else None,
        modelRoles=compact_json_dump(model_roles) if model_roles else None,
        prefersDark=prefers_dark.value if prefers_dark else None,
        preserveEntityFolderContentRole=(
            "true" if preserve_entity_folder_content_role else None
        ),
        theme=theme.value if theme else None,
        uiSettings=compact_json_dump(ui_settings) if ui_settings else None,
        userAttributes=(
            compact_json_dump(user_attributes) if user_attributes else None
        ),
        nonce=nonce,
    )

    self._sign_url(url)
    return str(url)

build_workbook_url(content_id, external_id, name, **options)

Builds a signed embedding URL for a workbook.

Parameters:

Name	Type	Description	Default
content_id	str	ID of the workbook to embed, e.g. "da24491e".	required
external_id	str	Unique ID for the embed user.	required
name	str	Name for the embed user's name property.	required
**options	Any	Any of the optional keyword arguments accepted by build_url.	{}

Returns:

Name	Type	Description
str	str	Signed embedding URL.

Source code in src/omni/embed.py

def build_workbook_url(
    self,
    content_id: str,
    external_id: str,
    name: str,
    **options: Any,
) -> str:
    """Builds a signed embedding URL for a workbook.

    Args:
        content_id: ID of the workbook to embed, e.g. "da24491e".
        external_id: Unique ID for the embed user.
        name: Name for the embed user's name property.
        **options: Any of the optional keyword arguments accepted by
            [build_url][omni.OmniEmbedder.build_url].

    Returns:
        str: Signed embedding URL.
    """
    return self.build_url(
        content_path=self._content_path("w", content_id),
        external_id=external_id,
        name=name,
        **options,
    )