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. This is shown in the sample code contained the previous embed help topic.

ParameterDescription
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.
account_typeThe embed user's Sigma member account type.
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

ParameterDescription
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.
hide_workbook_nameWhen set to true, hides the workbook name in the embed footer.
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 andEdit options, and Sigma logo in the embed footer.
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

ParameterDescription
account_type

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.

control_id
control_value
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.
showUnderlyingDataWhen set to true, displays the chart and its underlying data. Otherwise only the chart displays in the embed. Only applicable to embeds that contain a single visualization element.
oauth_tokenPasses secure tokens to Sigma to authenticate users and drive granular user permissions. For more information, see OAuth with Snowflake

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:

//PASS THE NAME OF THE USER ATTRIBUTE THAT IS CONFIGURED IN SIGMA AND THE VALUE TO SET IT TO:
searchParams += '&:ua_{ua name}={ua value}';

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

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