This document provides complete API reference for JWT structure and configuration options used across all embedding and sharing methods.Lightdash supports three ways to share embedded content:
Shareable URL — Generate a link that anyone can open directly in their browser, no iframe or SDK needed. Ideal for sharing dashboards with external users like clients or partners.
iframe embedding — Embed dashboards inside your own web pages using a standard <iframe> tag.
React SDK — Embed dashboards and charts in React/Next.js apps with full programmatic control.
All three methods use the same JWT-based authentication described below.For method-specific implementation details, see:
Embedded Lightdash content is available to view by anyone (not just folks with a Lightdash login). Content is secured using JWT (JSON Web Tokens) with configurable expiration times.
For embedding dashboards with multiple tiles, filters, and interactive features.
All configuration options (dashboardFiltersInteractivity, canExportCsv, canExplore, etc.) must be nested inside the content object — not at the top level of the JWT payload. A common mistake is placing these properties at the root level, which will cause them to be silently ignored.
{ content: { type: 'dashboard', // Dashboard identifier (required, use one) dashboardUuid?: string, dashboardSlug?: string, // Project identifier (optional) projectUuid?: string, // Filter interactivity dashboardFiltersInteractivity?: { enabled: 'all' | 'some' | 'none', // Required allowedFilters?: string[], // Required if enabled: 'some' hidden?: boolean, // Optional: hide filter UI }, // Parameter interactivity parameterInteractivity?: { enabled: boolean, }, // Export capabilities canExportCsv?: boolean, // Allow CSV export canExportImages?: boolean, // Allow image/PNG export canExportPagePdf?: boolean, // Allow PDF export // Interactive features canDateZoom?: boolean, // Allow date granularity zoom canExplore?: boolean, // Allow "Explore from here" canViewUnderlyingData?: boolean, // Allow viewing raw data canViewDataApps?: boolean, // Allow rendering data app tiles }, // Optional: User information for query tracking user?: { externalId?: string, email?: string, }, // Optional: User attributes for row-level filtering userAttributes?: { [attributeName: string]: string, },}
Chart tokens use contentId (the saved chart UUID) instead of dashboardUuid. Chart embeds are scoped to the specific chart and cannot access other content.
Allows users to view the raw data table behind visualizations.
canViewUnderlyingData?: boolean
When enabled, users can click on charts to open a modal showing the underlying data table. Data cannot be exported separately (use canExportCsv for that).
Allows data app tiles on an embedded dashboard to render and run their metric queries.
canViewDataApps?: boolean
Data app tiles run arbitrary metric queries against your semantic layer, so they need broader access than a standard chart tile. Enabling canViewDataApps grants the embed JWT the additional permissions a data app needs to mint a preview token and execute its queries. User attributes and SQL filters on the JWT still apply, so row-level access controls are enforced inside the data app exactly as they are on chart tiles.When this option is off (the default), data app tiles on the dashboard render as a placeholder and no queries run. Turn it on when you trust the embed audience to see the data the app can request and you want the tile to behave the same as it does in Lightdash.
For self-hosted deployments, you can configure new project embeds to allow all dashboards and/or charts by default using environment variables:
Variable
Description
Default
EMBED_ALLOW_ALL_DASHBOARDS_BY_DEFAULT
When creating new embeds, allow all dashboards by default
false
EMBED_ALLOW_ALL_CHARTS_BY_DEFAULT
When creating new embeds, allow all charts by default
false
When these are set to true, new project embeddings will automatically have all dashboards or charts allowed without needing to manually configure the allowed content list.See the environment variables reference for the complete list of embedding-related configuration options.
Pass user information to track who’s viewing embedded content.
user?: { externalId?: string, // Your internal user ID email?: string, // User's email address}
This metadata appears in query tags for usage analytics. If you don’t provide an externalId, Lightdash automatically generates one based on the embed token.Example:
