How to embed Metabase
into Embedportal.

Why this is needed

Metabase exposes two embedding modes: static and interactive. Static embedding uses JWT-signed URLs with locked parameters — exactly what multi-tenant SaaS embedding needs. Embedportal uses your embedding secret key to sign tokens that Metabase verifies server-side before rendering the dashboard.

works with — Metabase Open Source and Enterprise (Cloud and self-hosted). Static embedding is free in both.

Prerequisites

• A Metabase instance with admin access.
• At least one dashboard or question you want to embed.
• An Embedportal workspace (Professional or Enterprise plan).
• About 10 minutes.

Enable Static Embedding in Metabase

1. Sign in as admin. You need an administrator account on the Metabase instance.
2. Open Admin settings. Click the settings gear icon in the top right → Admin settings.
3. Toggle Enable Static Embedding. Navigate to Embedding in the left sidebar, and switch Enable Static Embedding to ON.

Copy the Embedding Secret Key

As soon as you enable static embedding, Metabase displays an Embedding Secret Key — a 64-character hexadecimal string. Copy it and paste it into Embedportal’s Secret Key field.

// example shape (yours will be different)
f7b2a1c9e4d8f3a2b7c1e9d4f8a3b2c7e1d9f4a8b3c2e7d1f9a4b8c3e2d7f1a9

important — this key signs every JWT. Never expose it in client-side code or commit it to a repo.

Enter the Metabase Site URL

Paste the base URL of your Metabase instance into Embedportal’s Metabase Site URL field.

Use the full URL with protocol, no trailing slash. This is the URL your browser uses to reach Metabase — not an API-specific endpoint.

Enable Embedding on Each Dashboard / Question

In Metabase, Static Embedding is enabled per resource. For every dashboard or question you want to surface in Embedportal:

1. Open the dashboard or question.
2. Click the sharing icon → pick the Embed option.
3. Select Static Embedding.
4. Toggle Enable to make the resource embeddable.
5. Copy the Dashboard ID (or Question ID) from the URL or embed code.
6. In Embedportal, add a navigation item with that ID.

This two-sided toggle is Metabase’s way of preventing accidental embed exposure. Any resource whose embed toggle is OFF stays private even if someone knows its ID.

Configure Allowed Origins (optional)

In Metabase’s embedding settings, add the domains that are allowed to embed your content. A typical entry is your Embedportal domain, for example dev.atspark.com or your custom white-labeled domain.

Allowed origins adds a browser-level defence layer on top of the JWT signature: even if someone steals a signed URL, their browser will refuse to render the iframe unless they’re on an allowed origin.

Fields you’ll fill in Embedportal

Click Save & Test Connection. Embedportal signs a test JWT, pings Metabase, and returns a green confirmation.

Row-level security (locked parameters)

Metabase’s equivalent of RLS is locked parameters. When you enable static embedding on a dashboard, you pick which parameters are locked — meaning they can only be set server-side on the signed token, not by the viewer in the UI.

In Embedportal, enable RLS on the dashboard and pick the attributes to forward. Embedportal signs the Metabase embed JWT with params filled from the viewer’s claims:

{
  "resource": { "dashboard": 42 },
  "params": {
    "organization_id": "ORG_ACME",
    "region": "emea"
  },
  "exp": 1747486500
}

For the vendor-agnostic setup, see Row-level security for embedded dashboards.

Security best practices

• Never expose the secret key in client-side code, public repos, or browser-accessible config.
• Rotate the embedding secret key at least annually (Metabase generates a new one with one click).
• Use allowed origins to restrict which domains can embed your content.
• Only enable embedding on dashboards that should be exposed externally.
• Use locked parameters for any attribute that scopes data — never rely on a viewer-editable parameter for access control.

Troubleshooting

• “Embedding is not enabled” — Metabase’s master toggle in Admin → Embedding is off. Turn it on.
• Dashboard renders but fails to load data — embedding is enabled globally but not on this specific dashboard. Open the dashboard’s Share menu and toggle Enable for static embedding.
• 400 Bad JWT signature — the secret key in Embedportal doesn’t match what Metabase has. Regenerate in Metabase and paste again.
• “This origin is not allowed” — your Embedportal domain isn’t on Metabase’s allowed origins list. Add it.
• Locked parameter appears editable — the parameter isn’t marked as Locked on the dashboard’s embed settings. Switch it from Editable to Locked.
• Metabase Site URL mismatch — if you change Metabase’s public URL (for example moving from http to https), update the Embedportal field too.