Dashboard embedding

Focus: Learn how to embed 5X Business Intelligence dashboards into your applications with secure authentication, access control, and customizable user experiences.

Dashboard embedding overview

Dashboard embedding enables you to integrate 5X Business Intelligence dashboards directly into your own applications via iframe. This provides a seamless way to bring data analytics into your native environment while maintaining security and access control.

Why embed dashboards?

Integrated experience

Seamless integrationProvide analytics within your application’s native interface for a cohesive user experience.

Reduced context switching

Stay in your appKeep users in your application instead of redirecting them to external BI tools.

Customized branding

Brand consistencyMaintain your application’s look and feel while providing powerful analytics.

Flexible deployment

Easy deploymentDeploy analytics capabilities without building custom visualization components.

Getting started with embedding

Two-step process

Dashboard embedding is organized into two main phases: Phase 1: Preparation

Collect required 5X BI asset information
Configure embedding settings and permissions
Gather technical details for integration

Phase 2: Deployment

Install the Superset Embedded SDK
Implement guest token generation
Embed dashboards in your application

Prerequisites

Required permissions:

Admin/Developer role access in your 5X workspace
Dashboard access - Ability to view and configure dashboards
API access - 5X API key for guest token generation

To obtain your 5X API key, please reach out to 5X Support at support@5x.co, contact us via Intercom, or reach out to your dedicated customer success manager.

Technical requirements:

Backend service - For secure guest token generation
Frontend application - For SDK integration and iframe embedding
HTTPS - Secure connection for embedded dashboards

Phase 1: Preparation

Enable dashboard embedding

Access your dashboard
- Navigate to the dashboard you want to embed
- Click the options menu (three dots) in the dashboard header
- Select “Embed dashboard”
Configure allowed domains
- Enter the domains where the dashboard will be embedded
- Include development and production domains
- Use full URLs with protocol (https:// or http://)

Domain configuration tips:

Wildcards are not supported - specify exact domains
Include all environments (dev, staging, prod)
Leave empty to allow embedding from any domain (not recommended for production)

Enable embedding
- Click “Enable Embedding”
- Save the provided Embedded Dashboard ID for use in your application

Collect required information

Embedded Dashboard ID:

Unique identifier for the embedded dashboard
Used with the Superset SDK to embed the dashboard
Required for guest token generation

Dashboard configuration:

Dashboard settings - Permissions, filters, and display options
Chart configurations - Individual chart settings and interactions
Filter settings - Global filters and their default values

Phase 2: Deployment

Step 1: Create guest tokens (Backend)

Guest tokens authenticate embedded users and define their data access permissions. They must be generated securely on your backend service. Guest token generation:

import requests
import json

def generate_guest_token(api_key, user_info, dashboard_ids, rls_rules):
    """
    Generate a guest token for embedded dashboard access
    """
    payload = {
        "user": {
            "username": user_info["username"],
            "first_name": user_info["first_name"],
            "last_name": user_info["last_name"]
        },
        "dashboardIds": dashboard_ids,
        "rls": rls_rules
    }
    
    response = requests.post(
        "https://api-v1.5x.co/business-intelligence/v1/guest-token",
        data=json.dumps(payload),
        headers={"Authorization": f"Bearer {api_key}"}
    )
    
    return response.json()["data"]["guestToken"]

Guest token parameters:

user (required) - User profile information
dashboardIds (required) - List of dashboard IDs the user can access
rls (required) - Row-level security rules for data access

Step 2: Supply guest tokens to frontend

Create an endpoint in your application that generates and returns guest tokens:

from flask import Flask, request, jsonify
from flask_login import login_required, current_user

@app.route("/api/guest-token", methods=["GET"])
@login_required
def get_guest_token():
    """
    Generate guest token for authenticated user
    """
    # Define RLS rules based on user context
    rls_rules = [
        {"clause": f"user_id = '{current_user.id}'"},
        {"clause": f"organization_id = '{current_user.organization_id}'"}
    ]
    
    guest_token = generate_guest_token(
        api_key=os.getenv("5X_API_KEY"),
        user_info={
            "username": current_user.username,
            "first_name": current_user.first_name,
            "last_name": current_user.last_name
        },
        dashboard_ids=["1", "2"],  # Dashboard IDs user can access
        rls_rules=rls_rules
    )
    
    return jsonify({"guestToken": guest_token})

Step 3: Install the Superset Embedded SDK

From NPM:

npm install --save @superset-ui/embedded-sdk

From CDN:

<script src="https://unpkg.com/@superset-ui/embedded-sdk"></script>

Step 4: Embed the dashboard

Using ES6 imports:

import { embedDashboard } from "@superset-ui/embedded-sdk";

// Embed dashboard in your application
const dashboard = await embedDashboard({
    id: "abc123", // Embedded Dashboard ID from preparation phase
    supersetDomain: "https://your-workspace.5x.co",
    mountPoint: document.getElementById("dashboard-container"),
    fetchGuestToken: () => fetchGuestTokenFromBackend(),
    dashboardUiConfig: {
        hideTitle: true,
        filters: {
            expanded: true,
        },
        urlParams: {
            param_name: "value",
            other_param: "value",
        },
    },
});

Using CDN:

<script src="https://unpkg.com/@superset-ui/embedded-sdk"></script>
<script>
    supersetEmbeddedSdk.embedDashboard({
        id: "abc123",
        supersetDomain: "https://your-workspace.5x.co",
        mountPoint: document.getElementById("dashboard-container"),
        fetchGuestToken: () => fetchGuestTokenFromBackend(),
        dashboardUiConfig: {
            hideTitle: true,
            filters: {
                expanded: true,
            },
        },
    });
</script>

Security and access control

Row-level security (RLS)

Row-level security provides fine-grained access control by applying additional WHERE clauses to data queries based on user context. RLS rule examples:

{
    "rls": [
        {
            "clause": "user_id = 'grace_hopper'"
        },
        {
            "dataset": 16,
            "clause": "environment = 'production'"
        },
        {
            "dataset": 42,
            "clause": "state = 'published'"
        }
    ]
}

RLS best practices:

Dataset-specific rules - Apply rules to specific datasets when possible
User context - Use user information to filter data appropriately
Security validation - Never insert untrusted input into RLS clauses
Testing - Thoroughly test RLS rules to ensure proper data filtering

Domain restrictions

Configure allowed domains:

Exact domain matching - Specify exact domains (no wildcards)
Protocol inclusion - Include https:// or http:// in domain specifications
Environment coverage - Include all relevant environments (dev, staging, prod)
Security review - Regularly review and update allowed domains

Authentication flow

Guest token lifecycle:

1-hour expiration - Guest tokens expire after 1 hour
Automatic refresh - SDK automatically refreshes tokens
Secure generation - Tokens generated only on trusted backend
No session persistence - Embedded dashboards don’t maintain 5X sessions

Best practices

Security best practices

Secure token generation

Backend onlyAlways generate guest tokens on your backend service, never expose API keys to frontend.

Principle of least privilege

Minimal accessGrant only the minimum permissions necessary for each user’s role and needs.

Regular security reviews

Ongoing monitoringRegularly review and audit access permissions and RLS rules.

Input validation

Validate inputsAlways validate and sanitize user inputs before using them in RLS clauses.

Troubleshooting

Common embedding issues

Authentication failures

Possible causes:

Invalid or expired guest tokens
Incorrect API key configuration
Missing user information in token
Network connectivity issues

Solutions:

Verify API key and token generation
Check user information completeness
Test network connectivity
Review token expiration handling

Data not displaying

Possible causes:

RLS rules too restrictive
Missing dashboard permissions
Data source connection issues
Query errors or timeouts

Solutions:

Review and adjust RLS rules
Verify dashboard access permissions
Check data source connections
Test queries independently

Display issues

Possible causes:

Incorrect iframe sizing
CSS conflicts with parent application
Responsive design problems
Browser compatibility issues

Solutions:

Adjust iframe dimensions and styling
Resolve CSS conflicts
Test responsive design
Check browser compatibility

Continue your Business Intelligence journey with these related guides.

Dashboard Creation

Create dashboardsBuild dashboards that can be embedded in your applications.

Get Started

Core Features