Embed URL parameters reference

Create and customize user sessions by including URL parameters in your embed requests. For example, you can use embed URL parameters to:

Specify user content roles
Assign connection and model roles to users
Control the look and theme of your embedded application
Apply user attributes to users

How sessions update embed users

Each embed session syncs the embed user to the parameters in that request. Omni doesn’t merge the new values with the user’s existing values. This means that if you leave out a value, Omni removes what that value set before. To keep a user’s access the same for each session, send the same values for every session.

If the request…	Omni…
Doesn’t include a group in `groups`	Removes the user from that group
Doesn’t include an attribute in `userAttributes`	Deletes that attribute from the user
Doesn’t include a connection in `connectionRoles`	Removes the user’s role on that connection, unless the connection backs the `contentPath`
Doesn’t include a model in `modelRoles`	Removes the user’s role on that model
Leaves out or changes `entity`	Moves the user out of their current entity
Doesn’t include `entityFolderContentRole` or `preserveEntityFolderContentRole`	Removes the user’s entity folder role
Includes `entity` without `entityAiCreditLimit`	Removes the credit limit override for all users in that entity; the organization’s default is applied.

Embed MCP tokens follow the same rules. If your embed URLs and MCP tokens use the same externalId, see Embed user MCP tokens for how to keep the user’s access consistent.

Parameter inclusion and URL signing formats

The signing format you use for embed URLs determines how parameters are included:

In the v1 signed payload format, all parameters are carried inside a single payload parameter, and JSON-valued parameters such as userAttributes stay as JSON instead of being stringified and URL encoded.
In the legacy v0 format, each parameter is sent as its own URL parameter.

A v1 payload also carries an exp expiry that isn’t listed below as it isn’t something you set per session in the same way. See URL expiry for more information.

All parameters

Valid embed requests must contain all required parameters. Recommended parameters aren’t required, but we strongly suggest that you include them.

Parameter	Required?	Description
contentPath		Defines the starting page when the embed user logs into the iframe.
externalId		Creates a unique ID for the embed user.
name		Defines a non-unique name for the embed user’s name property.
nonce		A unique 32-character string that defines the embed login URL.
connectionRoles		Specifies the level of access users will have to all models associated with a connection.
accessBoost		Enables AccessBoost for the embedded dashboard.
branch		Starts the embed session on a modeling branch instead of the published model.
customTheme		Defines custom theme properties for styling embedded dashboards.
customThemeId		Defines a theme ID from your Omni instance to stylize embedded dashboards.
email		Populates the from email for entity users when sharing content or sending deliveries.
entity		Defines a user group identifier used to associate the resulting embed user with a larger group.
entityAiCreditLimit		Sets an AI credit limit for the embed user’s entity group at login.
entityFolderContentRole		Specifies the content role the embed user will be given to their shared entity folder.
entityFolderGroupContentRole		Specifies the content role the embed entity group will be given to their shared entity folder.
entityFolderLabel		Updates the embed user’s associated entity folder label.
entityGroupLabel		Updates the embed user’s associated entity group label.
filterSearchParam		Specifies the filters to apply for the embedded content.
groups		Associates the resulting embed user with existing user groups in your Omni instance.
linkAccess		Controls which Omni dashboards can be linked to from the embedded dashboard.
mode		Defines the type of access users will have to Omni in the iframe.
modelRoles		Defines the level of access users will have for individual models in a connection.
prefersDark		Controls whether the resulting embed session has a light or dark mode appearance.
preserveEntityFolderContentRole		Retains the embed user’s existing entity folder content role.
theme		Customizes the styles of the resulting embed session with a built-in Omni application theme.
timezone		Specifies a timezone override for query execution in the embedded session.
uiSettings		Controls general settings of the application in embed.
userAttributes		Applies user attributes to the embed user.

Getting started

Setup

App customization

Events & interactivity

Admin

Embed URL parameters reference

How sessions update embed users

Parameter inclusion and URL signing formats

All parameters

​How sessions update embed users

​Parameter inclusion and URL signing formats

​All parameters

How sessions update embed users

Parameter inclusion and URL signing formats

All parameters