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 query 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/<organizationSlug>/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

You can refer to the example script and details to programmatically generate a secure embed URL signed with a JWT. The example script and environment variables file are provided for testing purposes and are not intended for use in a production deployment.

Use environment variables for testing

The example script uses environment variables, defined in an .env file, to provide required values. In a production deployment, your parent application would generate these values dynamically. For instructions on how to generate the embed client ID and secret, see Generate embed client credentials.

# .env file

# Required Embed Configuration
BASE_URL={URl of content to embed}
CLIENT_ID={embed client ID}
SECRET={embed secret}

# User-Specific JWT Claims
EMAIL={email address of the embed user}
ACCOUNT_TYPE={account type to assign to non-internal embed user}
TEAM={team to assign to non-internal embed user}

Example server-side API with JWT

You can refer to the following example script when you define the server-side code that you use to embed Sigma. The script is written in JavaScript and does the following:

• Uses the jsonwebtoken package to generate a JWT. If you use a different library, refer to the documentation for that library to identify how to pass claim values.
• Passes relevant JWT claims from an environment variables file to the jwt.sign() function used by the jsonwebtoken package.
• Passes team and account_type values for non-internal embed users. If you have embed users with accounts in Sigma, do not assign values for these claims. See Manage access to a secure embed for more details.
• Logs the decoded JWT and other details to the browser console for debugging purposes. Logging sensitive information to the browser console is not recommended for a production deployment.

Review the example script:

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/{organizationSlug}/workbook/{workbookId}?: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.