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 supports 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.

If you want to link to a tagged version of a workbook, reference the tag in the URL. See Link to a tagged version of a workbook.

📘

Unless otherwise noted, 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.

If a parameter contains multiple values, do not encode the commas separating the values. In your URL, the value of your parameter should be passed to Sigma as value1,value2 rather than value1%2Cvalue2.

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 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 users, affecting all sessions for those users.

Example use cases for user attributes:

• Enforce row-level security (see QuickStart - Embedding 06: Row Level Security > Dataset RLS with UA)
• Custom SQL WHERE clause (see QuickStart - Embedding 06: Row Level Security > Custom SQL Query)
• Dynamic warehouse role switching (see QuickStart - Embedding 09: Dynamic Role Switching with Snowflake)

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';