Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

[chore] Update llms.txt for master (#68561)

github-automation-metabase9a19a5e4f020
diff --git a/llms-embedding-full.txt b/llms-embedding-full.txt
index 231702b4be9..d896c7f4f66 100644
--- a/llms-embedding-full.txt
+++ b/llms-embedding-full.txt
@@ -1437,12 +1437,16 @@ Guest embeds are a way to embed basic Metabase components in your app without re
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](./static-embedding-parameters.md#restricting-data-in-a-static-embed-with-locked-parameters).
+To restrict data in guest embeds for specific people or groups, use [locked parameters](#locked-parameters).
## Turning on guest embedding in Metabase
-1. Go to **Settings > Admin settings > Embedding > Guest embeds**.
-2. Toggle **Enable guest embedding**.
+The path to embedding settings depends on your Metabase version:
+
+- **OSS**: **Admin settings > Embedding**
+- **Starter/Pro/Enterprise**: **Admin settings > Embedding > Guest embeds**
+
+Toggle **Enable guest embeds**.
## Creating a guest embed
@@ -1520,30 +1524,151 @@ Replace `YOUR_METABASE_SECRET_KEY` with your [embedding secret key](#regeneratin
You can set different attributes to enable/disable UI. Here are some example attributes:
-| Attribute | Description |
-| -------------------- | -------------------------------------------------------------------- |
-| `token` | Required. The signed JWT token from your server. |
-| `with-title` | Show or hide the title. Values: `"true"` or `"false"`. |
-| `with-downloads` | Enable or disable downloads. Values: `"true"` or `"false"`. |
-| `initial-parameters` | JSON string of parameter values. Example: `'{"category":["Gizmo"]}'` |
+| Attribute | Description |
+| -------------------- | --------------------------------------------------------------------- |
+| `token` | Required. The signed JWT token from your server. |
+| `with-title` | Show or hide the title. Values: `"true"` or `"false"`. |
+| `with-downloads` | Enable or disable downloads. Values: `"true"` or `"false"`. |
+| `initial-parameters` | JSON string of parameter values. Example: `'{"category":["Gizmo"]}'`. |
-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](./components.md).
+Attributes will differ based on the type of thing you're embedding. Guest embeds have fewer options than embeds that use SSO. See more on [components and their attributes](./components.md).
### Customizing appearance of guest embeds
-Appearance settings available for guest embeds depend on your Metabase plan. If you're running Metabase OSS/Starter, you can select light or dark theme. If you're running Metabase Pro/Enterprise, you'll have access to granular customization options, see [Appearance](./appearance.md)
+Appearance settings available for guest embeds depend on your Metabase plan. If you're running Metabase OSS/Starter, you can select light or dark theme. If you're running Metabase Pro/Enterprise, you'll have access to granular customization options, see [Appearance](./appearance.md).
-## Editing parameters on an embedded question or dashboard
+## Configuring parameters
-If you change the [parameters](./static-embedding-parameters.md) of your embedded item:
+Parameters are disabled by default, which also makes them hidden from end-users. You can configure each parameter to be:
-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.
+- **Disabled**: Hidden from end-users. Can't be set. This is the default.
+- **[Editable](#editable-parameters)**: End-users can see and modify the parameter values.
+- **[Locked](#locked-parameters)**: Hidden from end-users, set by your server (not the end-users) via the JWT.
-## Disabling embedding for a question or dashboard
+To configure parameters:
+
+1. Go to your embedded question or dashboard.
+2. Click the **sharing icon** and select **Embed**.
+3. Under **Parameters**, select the visibility option for each parameter, and optionally default value(s).
+4. Click **Publish**.
+
+### Editable parameters
+
+When you set Editable parameters, you can set default values for the filters, but users can change these when viewing the question or dashboard.
+
+**Server code**
+
+On the server, you pass an empty `params` object:
+
+```javascript
+// you will need to install via 'npm install jsonwebtoken' or in your package.json
+
+const jwt = require("jsonwebtoken");
+
+const METABASE_SECRET_KEY = "YOUR_METABASE_SECRET_KEY";
+
+const payload = {
+ resource: { dashboard: 10 },
+ params: {},
+ exp: Math.round(Date.now() / 1000) + 10 * 60, // 10 minute expiration
+};
+const token = jwt.sign(payload, METABASE_SECRET_KEY);
+```
-You can find a list of all guest embeds of questions and dashboards from **Admin settings** > **Embedding** > **Guest embeds**.
+**Client code**
+
+You set default parameters on the client side with the `initial-parameters` key.
+
+```html
+<script defer src="YOUR_METABASE_URL/app/embed.js"></script>
+<script>
+ function defineMetabaseConfig(config) {
+ window.metabaseConfig = config;
+ }
+</script>
+
+<script>
+ defineMetabaseConfig({
+ isGuest: true,
+ instanceUrl: "YOUR_METABASE_URL",
+ });
+</script>
+
+<!--
+THIS IS THE EXAMPLE!
+NEVER HARDCODE THIS JWT TOKEN DIRECTLY IN YOUR HTML!
+
+Fetch the JWT token from your backend and programmatically pass it to the 'metabase-dashboard'.
+-->
+<metabase-dashboard
+ token="YOUR SIGNED TOKEN"
+ with-title="true"
+ with-downloads="false"
+ initial-parameters='{"category":["Doohickey","Gizmo"]}'
+>
+</metabase-dashboard>
+```
+
+### Locked parameters
+
+Locked parameters let you filter data without exposing the filter to the end-user. This is useful for restricting data based on who's viewing the embed (for example, showing each customer only their own data).
+
+To use locked parameters, you need to:
+
+1. Set the parameter to **Locked** in the embed settings.
+2. Include the parameter value in your JWT token on the server.
+3. Publish the item.
+
+Here's an example of the server and client code that Metabase will generate if you lock a "category" parameter:
+
+**Server code (Node.js)**
+
+You set the locked parameter on the server, passing it in the token.
+
+```javascript
+// Install via 'npm install jsonwebtoken'
+const jwt = require("jsonwebtoken");
+
+const METABASE_SECRET_KEY = "YOUR_METABASE_SECRET_KEY";
+
+const payload = {
+ resource: { dashboard: 10 },
+ params: {
+ category: ["Gadget"], // Set the locked parameter value to Gadget
+ },
+ exp: Math.round(Date.now() / 1000) + 10 * 60, // 10 minute expiration
+};
+
+const token = jwt.sign(payload, METABASE_SECRET_KEY);
+```
+
+**Client code (HTML)**
+
+The parameter is set by the JWT:
+
+```html
+<script defer src="YOUR_METABASE_URL/app/embed.js"></script>
+<script>
+ window.metabaseConfig = {
+ isGuest: true, // Must be set to guest
+ instanceUrl: "YOUR_METABASE_URL",
+ };
+</script>
+
+<!--
+IMPORTANT: Never hardcode JWT tokens directly in your HTML!
+Fetch the token from your backend and pass it to the component programmatically.
+-->
+<metabase-dashboard
+ token="YOUR_JWT_TOKEN"
+ with-title="true"
+ with-downloads="false"
+></metabase-dashboard>
+```
+
+The end user won't see the "category" filter, but the dashboard will only show data for the "Gadget" category (or whatever you passed to the "category" array in the `params` object in the server payload you used to sign the JWT).
+
+## Disabling embedding for a question or dashboard
1. Visit the embeddable question or dashboard.
2. Click the **sharing icon** (square with an arrow pointing to the top right).
@@ -1551,6 +1676,8 @@ You can find a list of all guest embeds of questions and dashboards from **Admin
4. Select **Guest embedding**
5. Click **Unpublish**.
+Admins can find a list of embedded items in **Admin settings > Embedding** (on Pro and Enterprise plans, check the **Guest embeds** tab).
+
## Removing the "Powered by Metabase" banner
![Powered by Metabase](./images/powered-by-metabase.png)
@@ -1561,7 +1688,7 @@ The banner appears on guest embeds created with Metabase's open-source version.
Your embedding secret key is used to sign JWTs for all of your embeds.
-1. Go to **Admin** > **Embedding** > **Guest embeds**.
+1. Go to **Admin settings > Embedding**. On Pro and Enterprise plans, check the **Guest embeds** tab.
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.
@@ -1605,6 +1732,12 @@ The signed JWT is generated using your [Metabase secret key](#regenerating-the-e
If you want to embed charts with additional interactive features, like [drill-down](https://www.metabase.com/learn/metabase-basics/querying-and-dashboards/questions/drill-through) and [self-service querying](../questions/query-builder/editor.md), see [Modular embedding](./modular-embedding.md).
+## Using guest embeds with the SDK
+
+If you're using the [Modular Embedding SDK](./sdk/introduction.md), and you also want to embed a question or dashboard using guest authentication, you'll still need to visit the item in your Metabase and publish the item. You can ignore the code the wizard generates, but in order for Metabase to know it's okay to serve the item, you need to publish it.
+
+One limitation, however, is that you can only have one type of authentication per page of your app. For example, on a single page in your app, you can't have both one question using guest authentication and another question using SSO.
+
## 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.
@@ -1612,16 +1745,16 @@ Because guest embeds don't require you to create a Metabase account for each per
Guest embeds can't take advantage of:
- [Row and column security](../permissions/row-and-column-security.md)
+- [Database routing](../permissions/database-routing.md)
- [Drill-through](https://www.metabase.com/learn/metabase-basics/querying-and-dashboards/questions/drill-through)
-- [Usage analytics](../usage-and-performance-tools/usage-analytics.md).
+- [Usage analytics](../usage-and-performance-tools/usage-analytics.md)
- [Query builder](../questions/query-builder/editor.md)
-- [AI chat](./sdk/ai-chat.md).
+- [AI chat](./sdk/ai-chat.md)
For those features, check out [Modular embedding with SSO](./modular-embedding.md).
## Further reading
-- [Parameters for guest embeds](./static-embedding-parameters.md).
- [Reference apps repo](https://github.com/metabase/embedding-reference-apps).
- [Strategies for delivering customer-facing analytics](https://www.metabase.com/learn/metabase-basics/embedding/overview).
- [Publishing data visualizations to the web](https://www.metabase.com/learn/metabase-basics/embedding/charts-and-dashboards).