Embed URL parameters

All embed URL parameters serve a specific purpose in determining embed functionality, security, and compliance with licensing requirements. Sigma's embed URL requires a defined set of parameters and support several optional parameters that allow you to further customize and enhance the embed user experience. For example, you can use the optional parameters to create dynamic embeds based on service tiers, roles, etc.

This document provides an overview of all required and optional embed URL parameters. For more information about using parameters, see QuickStart - Embedding 05: Parameters and User-Attributes.

Required parameters

The following parameters must be appended to the base URL (embed path) in the embed URL.

Each parameter needs to be prepended in code with a colon (:). For example, the parameter "nonce" should appear as ":nonce" in code. See Example embed API and URL.

nonceA unique, random string used for security purposes. The value is valid for a single request.
client_idThe ID paired with and used to define the embed secret.
modeThe embed type (must be set to userbacked for secure embeds)
emailThe email address linked to the embed user's account.
external_user_idA unique identifier for the embed user. This can be the user_id value from the host application's security system or another value associated with the individual user.
external_user_teamThe Sigma team referenced to determine access and permissions.
session_lengthThe duration (in seconds) of the embed URL's browser session validity. Must be refreshed after expiration.
timeA UNIX timestamp used with the session_length parameter.
signatureA Hash-based Message Authentication Code (HMAC) signature produced by combining the encrypted embed secret with a hash function. Unique to the message and key, the cryptographic signature authenticates the request and protects data integrity. This ensures only parties with access to the secret key can verify the authenticity of the message.

Optional interface parameters

disable_mobile_viewWhen set to yes, disables automatic resizing mobile layout.
lngApplies an existing translation (via localization) to the embed.
first_nameSets the first name of the current embed user. When set, the name displays in the folder menu and system-generated emails. Must be used with the last_name parameter. When one or both is absent, a new member created in Sigma is named Embed (first) User (last).
hide_folder_navigationWhen set to true, hides the folder navigation. Available with mode=userbacked only.
hide_menuWhen set to true, hides the embed menu in saved workbooks.
hide_run_as_recipientWhen set to true, hides the Run queries as recipient option in the Send Now and Schedule Exports modals.
hide_scheduleWhen set to true, hides the Schedule exports option in the embed menu in saved workbooks.
hide_sendWhen set to true, hides the Send now option in the embed menu in saved workbooks.
hide_sheet_interactionsWhen set to true, hides the sort and filter options in embedded elements.
hide_tooltipWhen set to true, hides chart mark tooltips.
last_nameSets the last name of the current embed user. When set, the name displays in the folder menu and system-generated emails. Must be used with the first_name parameter. When one or both is absent, a new member created in Sigma is named Embed (first) User (last).
loading_bgApplies a custom background color (hex code) to the loading and error screens.
loading_textApplies a custom font color (hex code) to the loading and error screens.
menu_positionChanges the toolbar position (top, bottom) or removes it (none). When no value is specified, the toolbar defaults to the bottom position.
responsive_heightWhen set to true, enables developer access to the JavaScript event called workbook:pageheight:onchange.

For more information, see QuickStart - Embedding 10: Responsive Embeds > Responsive iframes
show_footerWhen set to false, hides the file explorer, workbook page tabs, Save As and Edit options, and Sigma logo in the embed footer.
showUnderlyingDataWhen set to false, hides the underlying data for a chart. Only applicable to embeds that contain a single visualization element.
themeApplies a default workbook theme (Light, Dark, or Surface) or any custom theme defined for your organization. The value must be the name of the theme (case-sensitive).
use_user_nameDisplays the workbook owner's name (instead of email) in the embed menu and system-generated emails.

Optional security parameters


Applies the permissions granted to the specified account type.

Recommendation: Set a value with the lowest level of permissions (for example, Viewer), unless the embed users must be granted a higher level of access.

The control_id parameter identifies a specific control element in the embedded content, and the control_value parameter sets the control value to customize the content displayed to the embed user.

Optional user attribute parameters

User attributes are variables that Admin users can create in Sigma. The host application uses the embed API to send user attribute parameters and update values at runtime for individual user sessions.

Example use cases for user attributes:

Example JavaScript for a user attribute:

searchParams += '&:ua_{ua name}={ua value}';

// searchParams += '&:ua_Region=East';

// or for multiple values:
// searchParams += '&:ua_Region=East,West';