Create an embed API with JSON Web Tokens

Sigma authenticates secure embeds using JSON Web Tokens (JWTs). JWTs offer a secure way to embed content that can be accessed by both external users (users who do not have a registered account in Sigma) and internal users (users who access Sigma directly through their Sigma account).

Configure your URL

You need to configure a URL for your embed by building out a base URL and then adding the specific parameters and claims you want to use:

• What URL to use
• Add your JWT claims
• Apply URL control values and string parameters
• Example script to generate a JWT-signed secure URL
• Example server-side API with JWT

What URL to use

When you decide to embed content, identify the URL for the content that you want to embed, then add claims and query string parameters to that base URL. Depending on what you want to embed, the structure of the URL is different.

🚧

The URL structure examples use brackets < and > to identify placeholder values that need to be replaced. Do not use the brackets in your URL. For example, a workbook URL looks like the following: https://app.sigmacomputing.com/sigma-docs/workbook/Example-Workbook-1aaaaaaaa2BBBB3CCCCCCCdE

After identifying the URL for the content that you want to embed, add JWT claims to the URL.

💡

If you retrieve document URLs from the API, such as with the List workbooks or List data models endpoints, the URL structure is formatted differently:

https://app.sigmacomputing.com/<organization-slug>/workbook/<workbookName>/<workbookId>

The URL format returned by API endpoints is also supported for embed URLs.

Add your JWT claims

To manage access to your secure embed and control other functionality, add JWT claims to the URL.

For a list of the available claims and how to use them, see JWT claims reference.

Sign your JWT with client credentials and secret

Use client credentials in your JWT to secure access to the embedded content:

1. Provide your client ID in the kid claim.
2. Provide your client secret using a JWT package for your preferred coding language. For example, the JavaScript example uses the jwt.sign function available from the jwt library.

Apply URL control values and query string parameters

You can control additional functionality with query string parameters that you add to your URL. For example, set control values to pre-populate filters in a workbook page, or specify the language of the embedded content to use translated content.

• For embed-specific query string parameters, see Embed URL parameters.
• To pre-populate the values of a control in an embedded workbook or workbook page, you can set control values in the URL with query string parameters, also called URL parameters. See Set control values in a URL using query string parameters.

Example script to generate a JWT-signed secure URL

The following script demonstrates how to programmatically generate a secure URL signed with a JWT.

The script makes use of an environment file for some required values. In a production environment, these values would be generated dynamically by the parent application. See Generate embed client credentials for instructions on how to generate the embed client id and secret.

# .env file

# Required Embed Configuration
BASE_URL={url path to embed}
CLIENT_ID={your client id}
SECRET={your embed secret}

# User-Specific JWT Claims
EMAIL={your embed user's email}
ACCOUNT_TYPE={embed user's account type}
TEAM={embed user's team}

Example server-side API with JWT

Values in the .env file (except keys) are typically generated at runtime by the parent application. This example script is written in JavaScript and uses the jsonwebtoken package. Refer to the documentation for the package you use for the construction of the JWT and how to pass claims.

const jwt = require('jsonwebtoken');
const { v4: uuid } = require('uuid');
const dotenv = require('dotenv');

dotenv.config();

async function generateSignedUrl() {
    try {
        const time = Math.floor(Date.now() / 1000); // Current Unix timestamp
        const expirationTime = time + Math.min(parseInt(process.env.SESSION_LENGTH) || 3600, 2592000);

        // Convert TEAM into an array if it is a single value
        const teamsArray = process.env.TEAM ? [process.env.TEAM] : [];

        const token = jwt.sign({
            sub: process.env.EMAIL,
            iss: process.env.CLIENT_ID,
            jti: uuid(),
            iat: time,
            exp: expirationTime,
            account_type: process.env.ACCOUNT_TYPE,
            teams: teamsArray,
        }, process.env.SECRET, {
            algorithm: 'HS256',
            kid: process.env.CLIENT_ID
        });

        // Decode the JWT to inspect its content and log it
        const decodedToken = jwt.decode(token, { complete: true });
        console.log('Decoded JWT:', decodedToken); // Log the decoded JWT for debugging
        
        const signedEmbedUrl = `${process.env.BASE_URL}?:jwt=${encodeURIComponent(token)}&:embed=true`;
        // Log important configuration details to ensure they are correctly set
        console.log('BASE_URL:', process.env.BASE_URL);
        console.log('CLIENT_ID:', process.env.CLIENT_ID); // Verify the client ID
        console.log('SESSION_LENGTH:', process.env.SESSION_LENGTH);
        console.log('TEAMS:', teamsArray);
        console.log('ACCOUNT_TYPE:', process.env.ACCOUNT_TYPE);
        console.log('Signed Embed URL:', signedEmbedUrl);

        return signedEmbedUrl;
    } catch (error) {
        console.error("Failed to generate JWT:", error);
        throw new Error("JWT generation failed");
    }
}

module.exports = { generateSignedUrl };  

The resulting signedUrl follows this structure:

https://app.sigmacomputing.com/{organization-slug}/workbook/{workbook_id}?:jwt={JWT VALUE}&:embed=true

For a detailed discussion and demonstration of using JWT when embedding Sigma, see Embedding 03: Using JWT Claims and Embed Parameters in the Sigma QuickStarts.