Signed Embedding vs. Public Embedding in Metabase

Metabase offers two embedding modes: public embedding, which makes a dashboard accessible to anyone without authentication, and signed embedding, which uses cryptographically signed JWT tokens to control exactly what each viewer sees. The right choice depends entirely on whether different users need to see different data, and whether the data is sensitive.

---

Public Embedding

Public embedding generates a static URL for a dashboard or question. Anyone who has the URL can view the content — no login, no token, no authentication required.

How to Enable Public Embedding

• Open the dashboard in Metabase

The URL looks like:

https://your-metabase.com/public/dashboard/abc123-def456-...

Metabase generates this URL when you enable public sharing. You can revoke it at any time by disabling public sharing on the dashboard.

Embed Code

Metabase provides ready-to-paste embed code:

html
<iframe src="https://your-metabase.com/public/dashboard/abc123-def456" frameborder="0" width="800" height="600" allowtransparency ></iframe>

When to Use Public Embedding

Public embedding is appropriate when:

When Not to Use Public Embedding

Do not use public embedding when:

A public embed URL is effectively a permanent, shareable link to your data. Anyone who finds or is forwarded the URL can view it. There is no per-user access control.

Filtering in Public Embeds

Public embeds support URL-based parameter filtering. You can pre-populate filters by appending them to the URL:

/public/dashboard/abc123#date=2024-01-01~2024-12-31®ion=us-west

Users can also change these filters in the dashboard UI unless you hide the filter controls. Note: because there's no signature, users can freely modify these parameters.

---

Signed Embedding

Signed embedding uses JSON Web Tokens (JWT) to authenticate embed requests. Your server generates a token containing the dashboard ID and any locked parameter values, signs it with a shared secret, and includes the token in the iframe URL. Metabase validates the signature before rendering the dashboard.

This is available in Metabase Pro and Enterprise only.

How Signed Embedding Works

1. Your server generates a JWT:
{ resource: { dashboard: 42 }, params: { organization_id: 99 }, exp: <10 minutes from now> } Signed with MB_EMBEDDING_SECRET_KEY 
JWT is included in the iframe URL:
/embed/dashboard/<jwt_token> 
Metabase receives the request:
- Verifies the signature (invalid = 401) - Checks expiry (expired = 401) - Applies locked params as immutable filters - Renders the dashboard 
User sees data filtered to organization_id = 99
User cannot change organization_id

When to Use Signed Embedding

Signed embedding is required whenever:

Signed vs. Public: Side by Side

Signed Embedding: Token Deep Dive

JWT Structure

A Metabase embed token is a standard JWT with this payload structure:

json
{ "resource": { "dashboard": 42 }, "params": { "organization_id": "99", "date_filter": "2024-Q1" }, "exp": 1735689600 }

The token is signed using HMAC-SHA256 (HS256) with the value of MB_EMBEDDING_SECRET_KEY.

Token Expiry

Token expiry (exp) should be set to a short window — 10 minutes is a common default. The token is used to load the dashboard; once loaded, the session continues even after the token expires (Metabase maintains a session internally). The expiry only applies to the initial load.

javascript
exp: Math.round(Date.now() / 1000) + (10 * 60)  // 10 minutes

For dashboards with auto-refresh, the page will reload and fetch a new token at refresh time, so short expiry doesn't cause problems.

Locking vs. Enabling Parameters

In Metabase's embedding configuration, each parameter on a dashboard can be:

Passing Enabled Parameter Defaults

Enabled parameters can be pre-populated via URL hash (not JWT), so users see a default value but can change it:

javascript
const baseUrl = ${METABASE_SITE_URL}/embed/dashboard/${token}; const hashParams = #date_filter=last30days®ion=us-west; const embedUrl = baseUrl + hashParams;

---

Choosing the Right Approach for Your Use Case

Use Public Embedding if:

Use Signed Embedding if:

Migrating from Public to Signed

Teams often start with public embedding to prototype, then migrate to signed embedding for production. The migration involves:

The dashboard content itself doesn't change — only the access mechanism.

---

Security Model Comparison

Public embedding security model: The URL is the credential. Anyone with the URL has access. Revocation requires disabling the public share entirely (affecting all viewers). There is no user identity, no audit trail, no expiry.

Signed embedding security model: The signed token is the credential. Access is determined by your server (which controls who receives a token). Tokens expire. Parameters are cryptographically locked. You can audit which users received tokens. You can revoke access by rotating the signing key or removing the user from your application.

For any production use case involving customer data, signed embedding is the only appropriate choice.

---

Summary

Public embedding is a permanent, unauthenticated URL — appropriate for non-sensitive data where all viewers see the same thing. Signed embedding uses short-lived, server-signed JWT tokens that lock parameters and enforce data isolation — required for any customer-facing or sensitive data use case. Most production SaaS deployments use signed embedding. The tradeoff is implementation complexity: signed embedding requires server-side code to generate tokens, while public embedding is just a URL in an iframe.