# How to Embed Superset Dashboards in External Applications Using the Embedded SDK

> Securely embed Superset dashboards in external apps with the Embedded SDK. Use guest tokens for isolated iframe authentication and seamless integration.

- Repository: [The Apache Software Foundation/superset](https://github.com/apache/superset)
- Tags: how-to-guide
- Published: 2026-03-03

---

**The Superset Embedded SDK renders dashboards inside isolated iframes using short-lived Guest Tokens for authentication, enabling secure integration into any web application.**

The Apache Superset Embedded SDK provides a production-ready solution to embed Superset dashboards and charts into external React, Vue, or plain JavaScript applications. By leveraging Guest Token authentication and cross-origin iframe sandboxing, the SDK ensures embedded analytics remain secure while offering extensive UI customization options. This guide walks through the complete implementation using source code from the `apache/superset` repository.

## Prerequisites: Enable Embedded Mode

Before embedding, the Superset backend must explicitly allow embedding via configuration.

The `EMBEDDED_SUPERSET` feature flag must be set to `True` in [`superset/config.py`](https://github.com/apache/superset/blob/main/superset/config.py). Additionally, each dashboard requires an embed configuration record (stored in [`superset/models/embedded_dashboard.py`](https://github.com/apache/superset/blob/main/superset/models/embedded_dashboard.py)) that registers allowed parent domains. Without these backend settings, the SDK’s iframe requests will be rejected with a 403 error.

## How the Superset Embedded SDK Works

### Guest Token Authentication

Authentication relies on **Guest Tokens**—short-lived JWTs created by calling the `POST /api/v1/security/guest_token` endpoint. These tokens grant scoped access to specific resources (dashboards or charts) and can include Row-Level Security (RLS) clauses for data filtering. The SDK receives these tokens via the `fetchGuestToken` callback you provide.

In [`superset-embedded-sdk/src/guestTokenRefresh.ts`](https://github.com/apache/superset/blob/main/superset-embedded-sdk/src/guestTokenRefresh.ts), the SDK decodes the JWT’s `exp` claim using `jwt-decode`, calculates the remaining time-to-live, and schedules an automatic refresh before expiration. This ensures uninterrupted user sessions without manual token management.

### Iframe Sandboxing and Security

The SDK creates a restricted iframe element with sandbox attributes defined in [`superset-embedded-sdk/src/index.ts`](https://github.com/apache/superset/blob/main/superset-embedded-sdk/src/index.ts). By default, it applies:

- `allow-same-origin`
- `allow-scripts`
- `allow-presentation`
- `allow-downloads`
- `allow-forms`
- `allow-popups`

You can extend these permissions via the `iframeSandboxExtras` parameter. For browser features like clipboard access or fullscreen mode, pass additional policies through `iframeAllowExtras`, which the SDK appends to the iframe’s `allow` attribute.

### Cross-Window Communication

The SDK establishes a two-way RPC channel between the host page and the Superset iframe using the **Switchboard** library and a `MessageChannel`. This channel, initialized in `embedDashboard` (lines 107-124 of [`src/index.ts`](https://github.com/apache/superset/blob/main/src/index.ts)), transmits the guest token to the iframe and receives events such as data mask updates from dashboard filters. The host application can also invoke iframe-side methods like `setThemeConfig` through this channel.

## Step-by-Step Implementation

### Install the SDK

Add the package via npm or load it from a CDN:

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

```

For CDN usage:

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

```

### Basic Dashboard Embed

Import `embedDashboard` from [`superset-embedded-sdk/src/index.ts`](https://github.com/apache/superset/blob/main/superset-embedded-sdk/src/index.ts) and mount the iframe to a DOM element:

```typescript
import { embedDashboard } from '@superset-ui/embedded-sdk';

async function fetchGuestToken(): Promise<string> {
  const resp = await fetch('/api/guest-token');
  const { token } = await resp.json();
  return token;
}

const container = document.getElementById('superset-container');

embedDashboard({
  id: 'abc123',                         // Dashboard UUID from Superset UI
  supersetDomain: 'https://superset.example.com',
  mountPoint: container,
  fetchGuestToken,
  dashboardUiConfig: {
    hideTitle: true,
    filters: { expanded: true, visible: true },
  },
});

```

The `dashboardUiConfig` object translates to URL parameters via the `calculateConfig` function. It maps options like `hideTitle` and filter visibility to the `DASHBOARD_UI_FILTER_CONFIG_URL_PARAM_KEY` query parameter, which Superset parses on load to adjust the UI layout.

### Listen to Dashboard Events

After embedding, you can observe filter changes and other data mask updates:

```typescript
const dashboard = await embedDashboard({ /* ... */ });

dashboard.observeDataMask((mask) => {
  console.log('Filter selection changed:', mask);
});

```

## Advanced Configuration

### Custom Sandbox Permissions

To allow top-level navigation or popup escapes, extend the sandbox attributes:

```typescript
embedDashboard({
  id: 'abc123',
  supersetDomain: 'https://superset.example.com',
  mountPoint: document.getElementById('embed'),
  fetchGuestToken,
  iframeSandboxExtras: ['allow-top-navigation', 'allow-popups-to-escape-sandbox'],
  iframeAllowExtras: ['clipboard-write', 'fullscreen'],
});

```

This modifies the iframe creation logic in [`src/index.ts`](https://github.com/apache/superset/blob/main/src/index.ts) (lines 90-97) where `iframe.sandbox.add()` applies your additional tokens.

### Control Referrer Policy

When Superset validates embedding domains via the `Referer` header, you may need to constrain the policy:

```typescript
embedDashboard({
  /* ... */
  referrerPolicy: 'same-origin',
});

```

The SDK sets `iframe.referrerPolicy` directly (lines 100-104 of [`src/index.ts`](https://github.com/apache/superset/blob/main/src/index.ts)), ensuring the browser sends the appropriate header with the initial iframe request.

### Custom Permalink Handling

Override Superset’s native share URLs by providing a `resolvePermalinkUrl` callback. The SDK registers this method on the Switchboard channel (lines 60-76 of [`src/index.ts`](https://github.com/apache/superset/blob/main/src/index.ts)), allowing you to rewrite internal permalinks to your application’s routing scheme:

```typescript
embedDashboard({
  /* ... */
  resolvePermalinkUrl: ({ key }) => {
    return `https://my-app.com/analytics/share/${key}`;
  },
});

```

## Backend Guest Token Generation

Your backend must generate Guest Tokens by authenticating to Superset’s REST API. Here is a Python implementation:

```python
import requests

SUPERSET_URL = 'https://superset.example.com'
ADMIN_JWT = 'your_admin_token'  # Obtained via /api/v1/security/login

payload = {
    "user": {"username": "embedded_user", "first_name": "Guest"},
    "resources": [{"type": "dashboard", "id": "abc123"}],
    "rls": [{"clause": "region = 'North America'"}]  # Optional RLS filtering

}

response = requests.post(
    f'{SUPERSET_URL}/api/v1/security/guest_token',
    json=payload,
    headers={'Authorization': f'Bearer {ADMIN_JWT}'}
)

guest_token = response.json()['token']

```

This token is then consumed by the SDK’s `fetchGuestToken` function. The RLS clauses ensure embedded users see only data subsets defined by your security rules.

## Summary

- **Enable the feature flag**: Set `EMBEDDED_SUPERSET = True` in [`superset/config.py`](https://github.com/apache/superset/blob/main/superset/config.py) and configure allowed domains in the dashboard embed settings.
- **Use Guest Tokens**: Implement a backend endpoint that calls `POST /api/v1/security/guest_token` to generate scoped, short-lived JWTs for authentication.
- **Mount with `embedDashboard`**: Import from `@superset-ui/embedded-sdk`, provide the dashboard UUID, Superset domain, and token fetcher to render the iframe.
- **Configure security**: Adjust `iframeSandboxExtras` and `iframeAllowExtras` for specific browser capabilities, and set `referrerPolicy` to match your domain validation strategy.
- **Handle lifecycle**: The SDK automatically refreshes tokens before expiration using logic from [`guestTokenRefresh.ts`](https://github.com/apache/superset/blob/main/guestTokenRefresh.ts), preventing session timeouts.
- **Customize URLs**: Provide `resolvePermalinkUrl` to rewrite share links for seamless integration with your host application’s navigation.

## Frequently Asked Questions

### What is a Guest Token in Superset embedding?

A Guest Token is a short-lived JWT generated by the Superset backend at `POST /api/v1/security/guest_token`. It authorizes an anonymous or embedded user to view specific dashboards or charts without requiring a full Superset login. The token contains claims for the user identity, resource IDs, and optional Row-Level Security (RLS) filters, and typically expires within minutes to minimize security exposure.

### How does the SDK automatically refresh authentication tokens?

The SDK decodes the JWT’s `exp` claim using the `jwt-decode` library and schedules a refresh using `setTimeout` before the token expires. Implemented in [`superset-embedded-sdk/src/guestTokenRefresh.ts`](https://github.com/apache/superset/blob/main/superset-embedded-sdk/src/guestTokenRefresh.ts), this logic subtracts a safety buffer from the remaining TTL and invokes your `fetchGuestToken` callback to obtain a new token, ensuring the embedded dashboard remains active without user interruption.

### Can I hide specific UI elements like the filter panel or title bar?

Yes. Pass a `dashboardUiConfig` object to `embedDashboard` with properties like `hideTitle: true` or `filters: { expanded: false, visible: false }`. The SDK encodes these options into URL parameters using the `calculateConfig` function in [`src/index.ts`](https://github.com/apache/superset/blob/main/src/index.ts), which Superset’s frontend interprets to conditionally render UI components when the iframe loads.

### What security risks does the iframe sandbox mitigate?

The default sandbox attributes (`allow-same-origin`, `allow-scripts`, etc.) prevent the embedded Superset instance from accessing the parent window’s DOM, cookies, or storage, protecting against XSS and clickjacking attacks. You can relax these restrictions via `iframeSandboxExtras` if your use case requires specific capabilities like top-level navigation, though this increases the attack surface and should be done cautiously according to the implementation in [`src/index.ts`](https://github.com/apache/superset/blob/main/src/index.ts) lines 90-97.