Embedding Superset dashboards in React with the embedded SDK
A product team that wants analytics inside its own application needs to know whether the Superset embedded SDK fits its React front end before any code is written. The SDK is a browser-side library. It mounts a Superset dashboard into an element on your page, handles the iframe communication, and exposes a small set of calls your app can make, such as setting filters or responding to errors. The SDK does not authenticate your users to Superset. That job belongs to your backend, which must call Superset's guest token endpoint on behalf of each signed-in user and return a short-lived guest token to the front end. The front end then passes that token to the SDK when it mounts the dashboard. Your React code therefore has two halves: a component that calls the SDK with a dashboard identifier and a token, and a backend route that decides which token each user receives.
Embedding fits best when your users should see analytics as part of your product, with your navigation, layout and session, and not as a separate Superset login. Teams usually choose it for customer-facing reporting, where each viewer's data must be scoped by the backend, and sending users directly to Superset would mean provisioning and managing a Superset account for each of them. If your users are internal staff who already have Superset accounts, linking to Superset directly is usually simpler to operate. Before you commit, confirm the SDK package version and its supported React and Superset versions against the Superset release you run, since embedding behavior and the guest token API have changed across releases. Check the current Superset documentation for the embedding section and the SDK's README, and test the mount, token refresh and error paths in a staging environment that matches your production Superset version.
Which parts of the integration you build
The integration has four parts that must agree with each other: Superset's embedding setup, a backend that issues guest tokens, a React component that calls the SDK, and the host app's own session. Each part can work alone in testing and still fail once the others are connected, so plan and verify them as one design.
Superset embedding setup
Superset must have embedded dashboards enabled for the dashboard you want to show, and that dashboard must carry an embed UUID that your app uses to identify it. The embedding configuration also determines which origins may frame the dashboard. Record the UUID per environment, since a staging dashboard and a production dashboard will have different values. Confirm the exact steps for enabling embedding and the allowed-domains setting against the Superset release you run, because these settings have changed between versions.
Guest token endpoint
A backend endpoint in your own service requests a guest token from Superset and returns it to the browser. This endpoint is where you decide who gets which dashboard and which row-level filters apply, so it must derive the tenant and user from your authenticated session, never from request parameters the browser controls. Keep the Superset service credentials on the server. Test that a user cannot request a token for another tenant's dashboard by changing an identifier in the request.
React component and SDK call
A React component calls the embedded SDK with the dashboard UUID, the Superset domain, and a function that fetches a fresh guest token. The component must mount the dashboard once, clean up on unmount, and handle token refresh without remounting the whole page. Check the SDK version pinned in your package file against the Superset release, because the SDK and the server must support the same embedding behavior. Test navigation between pages, since repeated mounts can leak listeners.
Host app session handling
Your application session, not Superset's login, decides whether the embedded view appears at all. When the host session expires, the component should stop requesting guest tokens and show your own sign-in prompt. Keep token lifetimes short, and make the token endpoint reject requests from sessions that have been revoked. Decide how the app behaves when Superset is unreachable, so users see a clear message rather than an empty frame.
Version-dependent items to confirm
Several behaviors are tied to the Superset release in use: the embedding configuration keys, the guest token request format, the SDK package and its options, and the iframe and cookie settings that browsers enforce. Read the upgrade notes for each release you plan to run, and rerun the embedding tests after every upgrade. Confirm these items against your release before you lock the design, rather than copying values from older tutorials.
Setting up the embedded dashboard in React step by step
This sequence moves a Superset dashboard from a private workspace into an iframe inside your React app, with your backend deciding who sees it. Each step ends with a check so that a fault is caught before the next layer depends on it. Confirm the Superset version, the SDK version and your authentication setup together during planning.
Enable embedding and record the embed ID
A Superset administrator turns on embedding for the instance and opens the target dashboard's embed settings. Record the embed ID shown there and store it in configuration, not in code that changes with each release. If your Superset version offers an allowed domains setting, limit it to the origin of your React app so no other site can frame the dashboard. Confirm the exact menu labels and feature flag name for your version in the embedding documentation. Check: reopen the embed settings and confirm the saved domains and embed ID match your change record.
Add a backend route for guest tokens
Your backend, not the browser, requests a guest token from Superset. The route first authenticates the caller with your existing session, then calls Superset's guest token endpoint using a service account limited to issuing embedded tokens. The request names the dashboard resource by embed ID and sets user claims such as username and first and last name, plus any row level security clauses for this viewer. Never accept the dashboard ID or filter values from the client. Check: call the route as a test user, decode the returned token and confirm the resource and claims match the request.
Install and pin the embedded SDK
In the React project, add the official Superset embedded SDK with your package manager and pin it to a version that matches your Superset release. Read the SDK documentation for the package name and compatibility notes before installing, because the release line you run determines which SDK build is supported. Move the Superset domain and embed ID into environment configuration so one build can run against staging and production. Check: the project builds, the lockfile records the pinned version and the configuration values load in the development environment.
Mount the dashboard with a token callback
Create a component that renders an empty container element. Inside an effect, call the SDK's embed function with the Superset domain, the embed ID, a reference to the container and a fetchGuestToken callback. The callback calls your backend route and returns the token string. Apply initial UI configuration options only after confirming them in the SDK documentation for your version. Return a cleanup function that removes the embedded dashboard on unmount so route changes do not leave duplicate frames. Check: after navigating away and back, the browser shows one iframe in the container.
Verify the load for test users
Sign in as a test user with access to the dashboard and open the page that hosts the component. Confirm the iframe loads, the charts render and the browser console shows no blocked-frame or cookie errors. If an error appears, resolve it in the cookie, Content Security Policy or CORS settings for your embedding origin before going further. Repeat with a second test user who has different row level security values and confirm the figures differ as expected. Check: each test user sees only the data their guest token allows.
Verify safe failure on an expired token
Force a failure path by issuing a token that has already expired, either with a short lifetime in a test environment or with a stub response from your backend. Confirm the frame shows no dashboard data and that your component displays a clear message with a retry action instead of a blank area. Confirm the token callback runs again on retry and that a valid token then loads the dashboard. Check: the failure is logged on both the backend and the client, and the retry path works in staging before you promote the build to production.
UI configuration options and when each fits
This table compares the mount options a team typically sets when embedding a Superset dashboard in a React app, with the purpose of each and when the default is enough. Option names and behavior change between Superset versions, so confirm each one in the embedded SDK documentation for your release before you rely on it. The main takeaway is that most options change what the viewer sees, not who can see the data, so access control stays in guest tokens and row level security.
| Option area | Purpose | When to keep the default | When to change it |
|---|---|---|---|
| Dashboard UI visibility | Controls whether Superset chrome such as the header and navigation appears inside the frame | Internal tools where users already know Superset | Customer-facing products that should look like part of your app |
| Filter bar | Shows or hides the native filter controls for the dashboard | Analysts who need to explore freely within their scope | Viewers should only see the filters your host page provides |
| Theme and branding | Applies brand tokens or a theme configuration to the embedded dashboard | Early prototypes and internal previews | Production embedding where fonts and colors must match the host app |
| Sizing behavior | Determines how the iframe height and width respond to content and container changes | Fixed-height dashboards with a predictable layout | Responsive layouts or dashboards with variable tab or chart counts |
| Debug and logging settings | Surfaces additional information in the browser console during development | Local development and staging | Disabled in production to avoid exposing internal detail |
| Error and loading states | Defines what the viewer sees while the dashboard loads or when a request fails | Standard behavior if your app already shows its own loading state | Apps that need consistent error messaging with the host design |
| Permalink and anchor settings | Controls how dashboard state such as filters or tabs is passed in the URL | Simple views with no saved state needs | Deep links from your app into a specific chart or filter state |
How resizing and error handling work in the host page
The host page has to manage two things the embedded dashboard cannot manage for itself: the height of the iframe and what the user sees when something fails. The SDK mounts Superset content inside an iframe, so the host layout must either give the frame a fixed height or respond to height messages that the embedded content sends to the parent window. Confirm in the SDK documentation which resize event the embedded dashboard emits, what payload it carries, and whether the host must listen on window or on a specific handler passed to the mount call. Then test the layout with the sidebar open and closed, on narrow viewports, and after a filter change that adds or removes chart rows, because those are the moments when a fixed height most often clips content or leaves a large gap.
Token and load failures need their own paths in your application code. Guest token fetches from your backend can fail on network errors, on a 401 or 403 from your own session check, or on a server error, and each should show a clear message and a retry rather than an empty frame. Expired tokens are the failure product teams most often miss in testing: a dashboard that loads correctly at first can stop refreshing after the token lifetime ends. Decide in advance whether the host refetches the token and remounts, asks the user to reload, or shows a session-ended state, and confirm the exact error and expiry events the SDK exposes for this. Also confirm how a dashboard that exists but fails to render, or a dataset the token does not allow, appears to the host.
Test these failure modes before release, using staging data and deliberately broken backend responses. The list should include an unreachable Superset host, a token endpoint that times out, a token that expires while the user is on the page, a dashboard ID that no longer exists, a dashboard with a query that fails, and a rapid unmount and remount when the user navigates away and back. For each case, record what the user sees, whether the host logs enough detail for your support team to diagnose it without exposing token contents, and whether the page recovers without a full browser reload. Treat the event names, handler signatures and payload shapes as details to verify against the current SDK release notes before you write code, since they are not fixed in this section.
Security considerations for guest tokens in the browser
A guest token is the only credential the browser holds for an embedded dashboard, so every risk below concerns what that token can reach and how long it lives. The cards cover where the service credential stays, how the token is scoped and how long it lasts, how row level security separates customers, the browser settings the iframe depends on, and what your team logs when tokens are issued.
Keep the service credential on the backend
Your backend holds the Superset service account used to request guest tokens from the embedded API, and that account can read every dashboard it is allowed to see. Never place its username, password or client secret in the React bundle, because anyone who opens the browser developer tools can copy it. Check your build output and environment handling, and confirm that only a short-lived guest token reaches the page.
Limit token lifetime and resources
A guest token should name only the dashboard it needs and should expire soon after issue. Ask your backend team to confirm the expiry setting in your Superset version and to refresh tokens through your own session checks rather than issuing long-lived ones. Each token resource should map to one dashboard, so a leaked token exposes one view instead of the whole workspace.
Scope row level security per customer
Guest token RLS clauses are how one customer is kept from seeing another customer's rows, and they are enforced by Superset, not by your React code. Test each tenant's token against sample data from every other tenant before release. The sibling page on guest tokens and row level security covers the rule design in detail, so use this card as the checklist item, not the implementation guide.
Set cookie and CSP headers for the iframe
The embedded dashboard runs in an iframe from your Superset origin, so browsers apply cookie and content security rules that can break the embed or widen your attack surface. Confirm that the frame-ancestors directive lists only your product's origins, and that session cookies carry the SameSite and Secure attributes your browsers require. Loosening these settings for convenience is the most common cause of exposure, so review each change. The sibling page on browser security settings explains the options.
Log every token issuance
Your backend should record each guest token request with the user or tenant identifier, the dashboard resource, the requested RLS clauses and the time. These logs let you answer which customer viewed which dashboard during an incident, and they support access reviews that auditors may ask for. Confirm where the logs are stored, how long they are kept, and who can read them, since the logs themselves reveal tenant structure.
Questions teams ask before building a Superset embed
How much effort does embedding Superset in a React app take?
Effort depends mostly on how many dashboards you embed, how many tenants or audiences see them, and how much of the authorization model already exists. The front-end work is usually the smaller part: mounting a dashboard with the SDK, handling sizing and errors, and passing filters from the host page. The larger parts are the backend endpoint that issues guest tokens, the row level security rules that scope each viewer's data, and the browser settings for cookies, CSP and CORS. A single internal dashboard for one audience is a different job from a multi-tenant, customer-facing product. Ask for the quote to split these components and to show which are one-time work and which recur when dashboards change.
Can an internal developer build a Superset embed without outside help?
Yes, if the developer has solid React experience, a backend service that can sign tokens, and access to a Superset administrator who can configure embedding and dataset permissions. The skills gap usually sits in the security design: deciding what a guest token may access, how long it lives, and how row level security rules are tested for leaks between customers. Teams without someone who owns that authorization model tend to lose time there. An outside partner can review that design, write the test plan and document the result, or hand the build to your own engineers with that material. Decide early which of those you need and write the split into the scope.
What must our team provide before an embedded Superset build starts?
The team needs five things ready before the build starts:
- Superset administrator access in a non-production instance, with rights to create the embedded dashboard and manage roles and datasets.
- A test dataset with the same column structure as production, including the fields your row level security rules will filter on.
- Your authentication design: which identity provider establishes the user session, how your backend maps users to tenants, and which services may request guest tokens.
- A host application environment and the list of origins where embeds will appear.
- A named owner for the metadata database, backups and upgrades of the Superset instance.
How long does it take to reach a first working embed?
The time to a first working embed depends on whether a Superset instance and test data already exist, how quickly access is granted, and how well the guest token endpoint's identity model is understood. A team with a running Superset, a built dashboard and a backend that already authenticates users can reach a first embed quickly. A new installation adds deployment work: choosing a production metadata database, since PostgreSQL or MySQL are the supported options rather than the SQLite default, and setting SECRET_KEY before the first start. Approvals for network paths, identity integration and data access often set the calendar more than the code does. Ask for a timeline that lists these dependencies separately.
Is the Superset embedded SDK safe to run in a regulated application?
The SDK is front-end code, so its safety depends on how you configure it and what surrounds it. The main risks sit in guest token issuance, row level security rules, cookie and Content Security Policy settings that control framing, and logging of who viewed what. No vendor or partner certifies an SDK for regulatory use. DeployOpen does not issue audit reports or certifications either. For SOC 2, an independent auditor tests your controls against the 2017 Trust Services Criteria, and a Type 1 report covers control design at a date while a Type 2 report covers operating effectiveness over a period. Ask for a threat model of the embed path, a leak test plan and evidence an assessor can review.
Does embedding Superset require a paid license or edition?
No paid edition exists for Apache Superset. It is an Apache Software Foundation project released under the Apache License 2.0 (SPDX: Apache-2.0), and the project has no paid edition, as shown on its PyPI package. Your costs come from infrastructure, the metadata database, caching and workers if you use alerts or async queries, internal staff time and implementation work. Have your legal team confirm that the Apache License 2.0 terms fit how you plan to ship the embed, and check any third-party components you add to the host app or plugins. A quote should show the core product's license as no charge and list infrastructure and services as separate lines.
Which Superset version should an embed project target?
Target a stable release you can upgrade on your own schedule, and confirm the SDK behavior and options against the documentation for that version. The published releases include 6.0.0, released December 18, 2025, and 6.1.0, released May 13, 2026. The GitHub releases page also lists 7.0.0rc2 as a pre-release dated October 16, 2026, which belongs in a test environment only. Each upgrade calls for a metadata database backup, superset db upgrade, superset init, staging tests and a review of UPDATING.md for breaking changes, as set out in the upgrade guide. Add embed checks to every upgrade: guest tokens, row level security filters and host page sizing should still work afterward.
Limits to confirm in your environment
The embedded SDK ties your app, your Superset version and your users' browsers together. Each card below is a limit that is easy to assume and expensive to discover after the build starts, so confirm them with the vendor and in your own test environment first.
SDK compatibility with your Superset version
The SDK has to match the Superset release you run, and Superset moves quickly. The PyPI listing shows Apache Superset 6.0.0 published on December 18, 2025 and 6.1.0 on May 13, 2026, and the GitHub releases page lists 7.0.0rc2 as a pre-release. Ask which SDK package version pairs with each server release, how long older pairings stay supported, and whether your planned upgrade cadence will outpace the SDK. Pin both versions in your build and test the pair together before each upgrade.
Browser and framework versions
The SDK runs inside your single-page app, so your supported browser list and your React version both constrain it. Confirm the minimum browsers and framework versions the SDK package declares, then compare them with the list your product actually supports, including older enterprise browser builds. Check whether the SDK ships its own TypeScript types and how it behaves under your bundler and any strict mode settings.
Iframe behavior in target browsers
The SDK mounts the dashboard inside an iframe, so embedding depends on how each target browser handles third-party frames, cookies and storage. Test sign-in, token refresh and resizing in every browser your users run, including those with strict tracking protection. Confirm which cookie settings Superset needs for cross-site embedding, since the browser security settings page covers SameSite and secure cookie requirements that vary by browser.
SDK licensing and support terms
Superset itself is released under the Apache License 2.0 and has no paid edition, but the SDK package and any supporting libraries you add carry their own license terms. Read the license file of each package you install and record it in your software bill of materials. Ask whether anyone offers support for the SDK, what response expectations come with it, and who fixes a defect in the SDK when the upstream project is slow to respond.
Dependence on an alpha operator
If your platform team plans to run Superset on Kubernetes, the official Helm chart is marked deprecated in current development docs, and the replacement Kubernetes Operator is in alpha with a v1alpha1 API that may change between releases. Confirm which deployment method your SDK embedding depends on, and avoid building your release process around custom resource schemas that could change under you.
Running the embed after go-live
Day-two work for an embedded React dashboard starts with knowing when guest tokens fail. Your backend endpoint that issues guest tokens is the first place to watch, because a Superset dashboard that loads for the wrong reason or fails to load at all usually traces back to a token request that returned an error, expired early or was built with the wrong resources. Log the status code, the dashboard identifier and the tenant identifier for every issuance, alert on sustained failures, and track how often the SDK's error handling path runs in the browser. Confirm with your Superset version which embedded and guest token settings your deployment exposes, because those affect what appears in those logs.
Every Superset upgrade needs a staging rehearsal of the embed before production. Read the release's UPDATING.md notes first, because breaking changes to the embedded endpoints, guest token claims or frontend behavior change what your backend and SDK calls must send. Back up the metadata database, run the upgrade in staging, then load each embedded dashboard for each tenant type and confirm that filters, resizing and sign-in redirects still behave. Treat a failed check as a blocker for the production upgrade, not as a note for later. Major versions warrant the most scrutiny, and the Upgrading Superset documentation lists the steps your runbook should mirror.
Rotating the SECRET_KEY is the change most likely to log out every embedded viewer at once if it is done carelessly. Set PREVIOUS_SECRET_KEY to the current key, deploy the new SECRET_KEY to every web and worker instance, and keep the old value in place until sessions issued under it have expired. Then remove it in a later change. Rehearse this in staging, and confirm the exact procedure for your version in the configuration documentation before you touch production.
Keep the React SDK version aligned with the Superset release you run. Pin the SDK in your lockfile, record the Superset version it was tested against, and make SDK upgrades part of the same staging check as the Superset upgrade. Ask your engineers to confirm the SDK's compatibility statement for each release, because a mismatch often shows up only as a blank iframe or a changed message contract.
How DeployOpen scopes and delivers this embed
DeployOpen plans, builds, tests and documents the Superset embedded SDK integration inside your own React or single-page app and your own Superset deployment. Engagements are fixed-scope, so the scope, deliverables and timeline for your embed are agreed in writing before any build work starts.
How we scope
- Map which dashboards or charts the React app mounts, and which user roles and tenants see each one.
- Define the backend endpoint that issues guest tokens and the identity claims it reads from your session.
- Agree in writing the UI configuration, resizing behavior, error states and the environments in scope.
How we build
- Wire the embedded SDK into your React components, including mounting, teardown and dashboard resizing.
- Implement the backend token service so guest tokens are requested per session with scoped resources and a short lifetime.
- Test that each viewer sees only their own data, and that errors such as expired tokens render cleanly in the host app.
How we hand over
- Deliver source code, configuration notes and a runbook for token rotation, Superset version changes and troubleshooting.
- Document the browser settings the embed depends on, so your team can review them with your security owners.
- Walk your engineers through the build and the test evidence so they can extend the integration without us.
How we support
- Offer ongoing support, Superset upgrades and continuous testing as a retainer after handover, if you want it.
- Re-run the cross-tenant data leak tests whenever Superset, the SDK or your dataset permissions change.
- Confirm with your team which support scope, response expectations and upgrade cadence apply before the retainer starts.
