We simplified embedding

TL;DR: If you’re embedding Metabase and upgrading to 58, you don’t have to do anything. Your existing embeds will continue to work exactly as before. These changes are about simplifying our embedding options so it’s easier for people to pick the option they need.

What changed

Starting in Metabase 58, there are two ways to embed Metabase for new embeds.

• Modular Embedding - Embed Metabase components, as Guest or as user via SSO.
• Full-app Embedding - The full Metabase, SSO only.

If you’re already embedding Metabase, your existing embeds still work. Static embedding will still work for existing embeds, but new embeds must use Modular Embedding.

How the old options map to the new

Why we changed our embedding options

They were confusing. Static embedding was also somewhat interactive, but we also had interactive embedding, which was a different thing. Each had a different setup flow. It worked, but figuring out the right path could have been easier, so that’s what we did. Plus, the new Modular Embedding provides an easier upgrade path from static embedding—you can start with Guest embeds and upgrade to SSO without major code changes.

Modular Embedding overview

We built an in-app wizard that walks you through setup and generates a code snippet. Copy, paste, done. The choice you have to make is whether you give people in your app a Metabase account. If you do, it unlocks a lot of stuff, and reduces your maintenance burden.

• Guest — People don’t need Metabase accounts. You sign embed URLs with JWT (just like static embedding), and they see the dashboard or question you’ve embedded. You can add and lock filters, but that’s about it. Guest embeds are available in the OSS Edition (with a “Powered by Metabase” badge) and on Pro/Enterprise.
• SSO — People authenticate through your identity provider and get their own Metabase account. And since your Metabase knows who’s viewing what, it can unlock everything: drill-through, the query builder, AI chat, collection browser, and more, all with the correct permissions applied. Self-service embedded analytics.

Modular Embedding has an SDK for React, so if your app uses React, you should go with the SDK.

The nice part: Guest and SSO embeds share the same foundation, so it’s a much smoother upgrade path from Guest to SSO.

Upgrading existing embeds to 58

You don’t have to do anything special when upgrading. Your existing embeds will continue to work exactly as before.

• Static embeds — Keep working. No code changes required. The iframe URLs, JWT signing, and parameter handling all work the same way. By default, you’ll see the new Modular Embedding wizard, but there’s an escape hatch: you can still access the legacy static embedding UI, configure embeds with the new wizard, and use the traditional iframe + JWT approach. Migrating to Modular Embedding SSO unlocks deep theming options that weren’t available with static embedding (Pro/Enterprise).
• Interactive embeds — Keep working. Now called “Full-app Embedding,” but nothing changes on your end.
• SDK embeds — Keep working. No changes to the SDK API. It’s just called the Modular Embedding SDK.

The only difference is what you’ll see in the Metabase UI when setting up new embeds.

Further reading

• Embedding docs
• Releases