Embed parameters
The following parameters can be used to customize the resulting embed user or session:
- In standard SSO embed these parameters are passed as URL query parameters
- In 2-step SSO embed, the majority of these parameters are included as a JSON payload in the
POST /generate-session
request
Required parameters
The following parameters are required to create a valid embed request.
contentPath
Defines the starting page when the embed user logs into the iframe.
URL builder label | Content path |
Required | Yes ✓ |
Accepted values | See below for example images of each page:
|
Example URL parameter |
|
Example pages
Dashboard (/dashboards/<dashboard-id>
)

Workbook (/w/<dashboard-id>/duplicate
)

My documents (/my
)

Entity folder (/entity-folder
)
An entity
parameter is required when /entity-folder
is used as the contentPath
.
By default, the entity
value will be used to create the entity folder.
To provide a different name for the folder, use the entityFolderLabel
parameter.

Hub (/root
)

externalId
Creates a unique ID. Alphanumeric values are supported.
URL builder label | External ID |
Required | Yes ✓ |
Example input(s) |
|
Example URL parameter |
|
name
Defines a non-unique name for the embed user's name
property.
URL builder label | Name |
Required | Yes ✓ |
Example input(s) |
|
Example URL parameter |
|
nonce
A 32-character string that defines the embed login URL. This must be unique or the session will fail to load.
Note: If using the SDK or /embed/sso/generate-url
endpoint, nonce
will be automatically added to the generated URLs if one is not provided.
URL builder label | Nonce |
Required | Yes ✓ |
Example input(s) |
|
Example URL parameter |
|
Recommended parameters
The following parameters are strongly recommended, but not required, in embed requests.
connectionRoles
Strongly recommended. An object of connection roles available for embed users. This parameter accepts an object of key-value pairs, formatted as "<connection_id>": "<connection_role>"
.
URL parameter |
|
Required | No X |
Accepted connection role values |
|
Example input(s) |
|
Example URL parameter |
|
Optional
The following parameters are optional in embed requests.
accessBoost
A boolean that enables AccessBoost for the embedded dashboard.
URL builder label | Access Boost |
Required | No X |
Accepted values |
|
Example URL parameter |
|
customTheme
Defines custom theme properties for styling embedded dashboards.
URL builder label | Custom theme |
Required | No X |
Accepted values | Refer to the Custom theme properties documentation for a list of available properties. |
Example URL parameter |
|
customThemeId
Defines a theme ID from your Omni instance, used to stylize embedded dashboards.
URL builder label | Custom theme ID |
Required | No X |
Example input(s) |
|
Example URL parameter |
|
email
Populates the from
email for entity users when sharing content or sending deliveries.
URL builder label | |
Required | No X |
Example input(s) |
|
Example URL parameter |
|
entity
Defines a user group identifier used to associate the resulting embed user with a larger group. Also creates the shared entity folder using the name set in the value. Can be any alphanumeric value.
URL builder label | Embed entity |
Required | No X |
Example input(s) |
|
Example URL parameter |
|
entityFolderContentRole
Specifies the content role the embed user will be given to their shared entity folder.
URL builder label | Entity folder content role |
Required | No X |
Accepted values |
|
Example URL parameter |
|
entityFolderLabel
Updates the embed user's associated entity folder label. Note: An entity
must be provided in the generated URL for this parameter to have an affect.
URL builder label | Entity folder label |
Required | No X |
Accepted values |
|
Example URL parameter |
|
entityGroupLabel
Updates the embed user's associated entity group label. Note: An entity
must be provided in the generated URL for this parameter to have an effect.
URL builder label | Entity group label |
Required | No X |
Accepted values |
|
Example URL parameter |
|
filterSearchParam
Specifies the filters to apply for the embedded content.
URL builder label | Filter search param |
Required | No X |
Example input(s) |
|
Example URL parameter |
|
groups
An array of user group names that associate the resulting embed user with existing user groups in your Omni instance.
URL builder label | Groups |
Required | No X |
Example input(s) |
|
Example URL parameter |
|
linkAccess
Controls which Omni dashboards can be linked to from the embedded dashboard.
URL builder label | Link access |
Required | No X |
Accepted values |
|
Example URL parameter |
|
mode
Defines the type of access users will have to Omni in the iframe.
URL builder label | Mode |
Required | No X |
Accepted values |
|
Example URL parameter |
|
prefersDark
Controls whether the resulting embed session has a light or dark mode appearance.
URL builder label | Prefers dark |
Required | No X |
Accepted values |
|
Example URL parameter |
|
theme
Customizes the styles of the resulting embed session with a built-in Omni application.
URL builder label | Built-in theme |
Required | No X |
Accepted values |
|
Example URL parameter |
|
userAttributes
Applies user attributes to the embed user.
URL builder label | User attributes |
Required | No X |
Example input(s) |
|
Example URL parameter |
|