Skip to main content

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

RequiredYes
Accepted values

See below for example images of each page:

  • Dashboard: /dashboards/<dashboard-id>
  • Workbook: /w/<dashboard-id>/duplicate
  • My documents: /my
  • Entity folder: /entity-folder. Requires an entity parameter. The folder will be named using the entity value unless an entityFolderLabel parameter is also provided.
  • Hub: /root
Example URL parameter

contentPath=%2Fdashboards%2Fa6908f35

Example pages

Dashboard (/dashboards/<dashboard-id>)
Workbook (/w/<dashboard-id>/duplicate)
My documents (/my)
Entity folder (/entity-folder)
note

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

RequiredYes
Example input(s)
  • sugar
  • &spice123
  • 123+EveryThingNice
Example URL parameter

externalId=ohtani17

name

Defines a non-unique name for the embed user's name property.

URL builder label

Name

RequiredYes
Example input(s)
  • Blobby
  • Blobby Hill
  • Blobfather
Example URL parameter

name=Blob+Ross

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

RequiredYes
Example input(s)

abcdefghijklmnopqrstuvwxyz123456

Example URL parameter

abcdefghijklmnopqrstuvwxyz123456

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

connectionRoles

RequiredNo X
Accepted connection role values
  • RESTRICTED_QUERIER - Can create new content and view workbooks and dashboards
  • VIEWER - Can only view dashboards
Example input(s)

{"connection-id-1":"RESTRICTED_QUERIER", "connection-id-2":"VIEWER"}

Example URL parameter

connectionRoles=%7B%2265b10d2a-473b-4486-92c8-0ba628c7d1cb%22%3A%22RESTRICTED_QUERIER%22%7D

Optional

The following parameters are optional in embed requests.

accessBoost

A boolean that enables AccessBoost for the embedded dashboard.

URL builder label

Access Boost

RequiredNo X
Accepted values
  • true
  • false
Example URL parameter

accessBoost=true

customTheme

Defines custom theme properties for styling embedded dashboards.

URL builder label

Custom theme

RequiredNo X
Accepted values

Refer to the Custom theme properties documentation for a list of available properties.

Example URL parameter

customTheme=%7B%22dashboard-background%22%3A%22blue%22%7D

customThemeId

Defines a theme ID from your Omni instance, used to stylize embedded dashboards.

URL builder label

Custom theme ID

RequiredNo X
Example input(s)

abcdefgh-ijkl-mnop-qrst-123456789123

Example URL parameter

customThemeId=abcdefgh-ijkl-mnop-qrst-123456789123

email

Populates the from email for entity users when sharing content or sending deliveries.

URL builder label

Email

RequiredNo X
Example input(s)

blobby@blobsrus.com

Example URL parameter

email=blobby17%40blobsrus.com

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

RequiredNo X
Example input(s)
  • Blobs R Us
  • Blobby Outdoors
  • Blob Mart
Example URL parameter

entity=Blobs+R+Us

entityFolderContentRole

Specifies the content role the embed user will be given to their shared entity folder.

URL builder label

Entity folder content role

RequiredNo X
Accepted values
  • VIEWER - Can see content in the shared folder, but cannot save content into it
  • EDITOR - Can see and save content into the shared folder
  • MANAGER - Can see and save content into the shared folder and manage other users' permissions
Example URL parameter

entityFolderContentRole=EDITOR

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

RequiredNo X
Accepted values

Blob Sales

Example URL parameter

entityFolderLabel=Blob+Sales

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

RequiredNo X
Accepted values

Blob Sales

Example URL parameter

entityGroupLabel=Blob+Sales

filterSearchParam

Specifies the filters to apply for the embedded content.

URL builder label

Filter search param

RequiredNo X
Example input(s)

f--order_items.status=closed

Example URL parameter

filterSearchParam=f--order_items.status%3D%257B%22values%22%253A%255B%22Complete%22%255D%252C%22appliedLabels%22%253A%257B%257D%257D

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

RequiredNo X
Example input(s)

["Blob Sales", "Blob Marketing"]

Example URL parameter

groups=%5B%22Blob+Sales%22%2C%22Blob+Marketing%22%5D

Controls which Omni dashboards can be linked to from the embedded dashboard.

URL builder label

Link access

RequiredNo X
Accepted values
  • __omni_link_access_open - All links on the embedded dashboard are permissed and shown
  • <list_of_dashboard_ids> - Only permit specific dashboards to be shown
  • Leave blank to restrict all links to other Omni dashboards. Note: Links to anything other than an Omni dashboard will be shwon regardless of the values specified in this parameter.
Example URL parameter

linkAccess=__omni_link_access_open

mode

Defines the type of access users will have to Omni in the iframe.

URL builder label

Mode

RequiredNo X
Accepted values
  • APPLICATION - Enables Create mode. Allows embed users to access the full content system and navigate through the Omni app in an iframe
  • SINGLE_CONTENT - Only embeds an individual dashboard or workbook. No content navigation or app headers.
Example URL parameter

mode=APPLICATION

prefersDark

Controls whether the resulting embed session has a light or dark mode appearance.

URL builder label

Prefers dark

RequiredNo X
Accepted values
  • true
  • false
  • system
Example URL parameter

prefersDark=false

theme

Customizes the styles of the resulting embed session with a built-in Omni application.

URL builder label

Built-in theme

RequiredNo X
Accepted values
  • vibes
  • dawn
  • breeze
  • blank
Example URL parameter

theme=vibes

userAttributes

Applies user attributes to the embed user.

URL builder label

User attributes

RequiredNo X
Example input(s)

{"country":"Townsville", "associated_ids":[9,10,11]}

Example URL parameter

userAttributes=%7B%22country%22%3A%22Townsville%22%2C%22associated_ids%22%3A%5B9%2C10%2C11%5D%7D