Guest embeds

Embed a real dashboard in just 30 minutes.

Join our next Embedded Analytics Workshop

Guest embeds are a way to embed basic Metabase components in your app without requiring you to create a Metabase account for each person viewing the charts and dashboards. But not logging people in to your Metabase has some major tradeoffs: see limitations.

Even though you’re not using SSO, guest embeds are still secure: Metabase will only load the embed if the request has a JWT signed with the secret shared between your app and your Metabase. The JWT also includes a reference to the resource to load (like the ID of the embedded item), and any values for parameters.

To restrict data in guest embeds for specific people or groups, use locked parameters.

Turning on guest embedding in Metabase

1. Go to Settings > Admin settings > Embedding > Guest embeds.
2. Toggle Enable guest embedding.

Creating a guest embed

To create a guest embed:

1. Go to the item that you want to embed in your website. You can also open a command palette with Ctrl/Cmd+K and type “New embed”.
2. Click the sharing icon.
3. Select Embed.
4. Under Authentication, select Guest.
5. Optional: customize the appearance of the embed
6. Optional: Add parameters to the embed.
7. Click Publish.
8. Get the code snippet that the wizard generates and add it to your app.

Notes on the code the wizard generates

You can edit the code (see components and appearance. But here’s an overview of the code the wizard generates, and where to put it.

Client-side code

Add the embed script and configuration to your HTML:

<script defer src="YOUR_METABASE_URL/app/embed.js"></script>
<script>
  window.metabaseConfig = {
    isGuest: true,
    instanceUrl: "YOUR_METABASE_URL",
  };
</script>

Then add the component for the item you want to embed:

<!-- For dashboards -->
<metabase-dashboard
  token="YOUR_JWT_TOKEN"
  with-title="true"
  with-downloads="false"
  initial-parameters='{"category":["Gizmo"]}'
></metabase-dashboard>

<!-- For questions -->
<metabase-question token="YOUR_JWT_TOKEN"></metabase-question>

Never hardcode JWT tokens directly in your HTML. Always fetch the token from your backend and pass the token to the web component programmatically.

Server-side code

Your server generates signed JWT tokens that authenticate the embed request. Here’s an example using Node.js:

const jwt = require("jsonwebtoken");

const METABASE_SECRET_KEY = "YOUR_METABASE_SECRET_KEY";

const payload = {
  resource: { dashboard: 10 }, // or { question: 5 } for questions
  params: {},
  exp: Math.round(Date.now() / 1000) + 10 * 60, // 10 minute expiration
};

const token = jwt.sign(payload, METABASE_SECRET_KEY);

Replace YOUR_METABASE_SECRET_KEY with your embedding secret key.

Component attributes

You can set different attributes to enable/disable UI. Here are some example attributes:

Attributes will differ based on the type of thing you’re embedding. Guest embeds have fewer options that embeds that use SSO. See more on components and their attributes.

Editing parameters on an embedded question or dashboard

If you change the parameters of your embedded item:

1. After making your changes, copy the code Metabase generates.
2. Click Publish again.
3. Update the code on your server so that it matches the code generated by Metabase.

Disabling embedding for a question or dashboard

You can find a list of all guest embeds of questions and dashboards from Admin settings > Embedding > Guest embeds.

1. Visit the embeddable question or dashboard.
2. Click the sharing icon (square with an arrow pointing to the top right).
3. Select Embed.
4. Select Guest embedding
5. Click Unpublish.

Removing the “Powered by Metabase” banner

The banner appears on guest embeds created with Metabase’s open-source version. To remove the banner, you’ll need to upgrade to a Pro or Enterprise plan.

Regenerating the embedding secret key

Your embedding secret key is used to sign JWTs for all of your embeds.

1. Go to Admin > Embedding > Guest embeds.
2. Under Regenerate secret key, click Regenerate key.

This key is shared across all guest embeds. Whoever has access to this key could get access to all embedded artifacts, so keep this key secure. If you regenerate this key, you’ll need to update your server code with the new key.

Custom destinations on dashboards in guest embeds

You can only use the URL option for custom destinations on dashboards with guest embedding. External URLs will open in a new tab or window.

You can propagate filter values into the external URL, unless the filter is locked.

Translating guest embeds

See Translating embedded questions and dashboards.

How guest embedding works

Guest embeds use web components (<metabase-dashboard> and <metabase-question>) that communicate with your Metabase instance. Each embed request requires a JWT token signed with your secret key.

When a visitor views your page:

1. Your server generates a signed JWT token containing the resource ID (dashboard or question) and any locked parameters.
2. The web component sends the token to Metabase.
3. Metabase verifies the JWT signature using your secret key.
4. If valid, Metabase returns the embedded content.

For interactive filters, you can pass initial parameter values via the initial-parameters attribute. When a visitor changes a filter, the web component handles the update automatically.

The signed JWT is generated using your Metabase secret key. The secret key tells Metabase that the request can be trusted. Note that this secret key is shared for all guest embeds, so whoever has access to that key will have access to all embedded artifacts.

If you want to embed charts with additional interactive features, like drill-down and self-service querying, see Modular embedding.

Guest embed limitations

Because guest embeds don’t require you to create a Metabase account for each person via SSO, Metabase can’t know who is viewing the embed, and therefore can’t give them access to all their data and all the cool stuff Metabase can do.

Guest embeds can’t take advantage of:

• Row and column security
• Drill-through
• Usage analytics.
• Query builder
• AI chat.

For those features, check out Modular embedding with SSO.

Example app with guest embed and theming

Check out our sample app. Bring your Metabase, embed a dashboard, and play around with changing colors.

Further reading

• Parameters for guest embeds.
• Reference apps repo.
• Strategies for delivering customer-facing analytics.
• Publishing data visualizations to the web.
• Customizing Metabase’s appearance.