Add URL parameters to a secure embed

After you generate a secure embed path that you plan to sign with your embed credentials, use specific query string parameters on the embed URL to define the functionality of your embed:

• Set required parameters.
• Customize functionality and display with interface parameters.
• Manage access and data security with security parameters and user attributes.

If you want to embed the tagged version of a workbook, reference the tag in the URL, then set query string parameters. See Link to a tagged version of a workbook.

The best way to construct the embed URL is with code. For an example using JavaScript, see Example embed API and URL.

This document provides an overview of all required and optional embed URL parameters.

Usage notes

Query string parameters are applied at the end of a URL path. The first parameter follows a question mark (?) and additional parameters are added after an ampersand (&).

For example:

https://app.sigmacomputing.com/embed/{embedID}?:nonce={nonce}&:client_id={CLIENT_ID}&:mode=userbacked

🚩

Unless otherwise noted, each parameter listed in these reference tables must be prepended with a colon (:). For example, the parameter "nonce" should appear as ":nonce" in your secure embed URL.

Values that you provide in the embed URL must be URL-encoded, with some exceptions:

• If you provide multiple values for a parameter, such as for a user attribute, separate each value with a comma. Do not URL-encode the comma.
• Key values, such as a user attribute name or value, a team, a custom account type, or a custom theme, must not be encoded. If your user attribute, account type, team, or theme name contains spaces or special characters other than an underscore (_), consider changing the name.

For details about how to URL-encode values, see Special characters for URL parameters.

Required parameters

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

Optional interface parameters

Optional security parameters

Optional user attribute parameters

User attributes are variables that users assigned the Admin account type can create in Sigma. The host application can use the embed API to apply user attribute parameters and update values at runtime for individual users, affecting all sessions for those users.

Example use cases for user attributes:

• Enforce row-level security for a dataset. TODO: link to new doc. See the section on dataset RLS with user attributes in the Embedding 06: Row Level Security Sigma QuickStart.
• Enforce row-level security using custom SQL with a WHERE clause. TODO: link to new doc. See the section on custom SQL query in the Embedding 06: Row Level Security Sigma QuickStart.
• Dynamically switch the role of a user to take advantage of RBAC in your data platform. TODO: link to new doc. See Embedding 09: Dynamic Role Switching with Snowflake in Sigma QuickStarts.
• Dynamically switch the Snowflake virtual warehouse to use different compute. TODO: link to new doc. See Embedding 09: Dynamic Role Switching with Snowflake in Sigma QuickStarts.

Construct a user attribute parameter for a secure embed URL

To construct a user attribute parameter for a secure embed URL, do the following:

• Prepend the name of the user attribute with :ua_
• Include the name of the user attribute.
• Set the user attribute parameter equal to one or more values

For example:

&:ua_Region=West,Midwest

📘

Do not encode any special characters in the name of the user attribute. If your user attribute contains special characters other than an underscore (_), consider renaming it.

Example code for user attribute parameters

Example JavaScript code to apply a user attribute parameter and value in the embed URL.

This example code assumes that you have two environment variables set up:

• uaName to store the name of the user attribute.
• uaValue to store the value of the user attribute.

//Pass the user attribute name from Sigma and value to set it to:
searchParams += '&:ua_{uaName}={uaValue}';

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

// or for multiple values:
// searchParams += '&:ua_{uaName}={uaValue1},{uaValue2}';
// searchParams += '&:ua_Region=East,West';