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.
User attributes enable row-level and column-level security by filtering data based on user properties. Column-level security is especially useful when embedded users can Explore from here, since it ensures restricted fields stay hidden in the explore view as well.
The JWT userAttributes field drives both row-level and column-level access controls, the same ones available to Lightdash account users:
Row-level filtering: attributes are substituted into any sql_filter on the dbt model (e.g. ${lightdash.attributes.tenant_id}), restricting which rows the embedded user can query.
Column-level filtering: attributes are matched against required_attributes and any_attributes rules on dimensions, metrics, and tables. Fields whose rules the embedded user’s attributes don’t satisfy are stripped from the explore entirely: they don’t appear in the field list, can’t be queried, and return Forbidden if requested directly. Metrics derived from a hidden dimension are hidden too.
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:
