API integration for Metabase
We build your Metabase connector
We embed Metabase in your application: each customer sees their own figures, filtered automatically, without opening a second tool.
- Senior product team
- Metabase embedding in production
- from scoping to monitoring
What does the Metabase integration do and why embed dashboards in your application?
Metabase is a business intelligence tool that lets business teams create reports and dashboards without writing SQL. Its API and embedding feature let you embed those dashboards directly in your application, filtered by client or scope, without the user having to log into a separate tool. You integrate it when clients or teams need to see their own data in context within your product, rather than receiving a CSV export or switching to an external reporting tool.
What our clients build on the Metabase API
Customer portal: my orders, my balance
JWT iframe, locked client_id from the session. The customer does not see Metabase, nor other accounts.
Internal back office as full app embedding
The analyst keeps the same groups as your directory, in the back office you control. One login.
Q&A assistant on sales
Agent API, the user's rights, not free SQL, not an admin key in the chatbot.
Monthly export of a card to PDF
Service-account session, not an analyst's password. Company 2FA / SSO break this flow if it is aimed at a human.
What this changes in your product
Engineering in service of a measurable outcome: figures in the portal, same system of record, each account sees its rows.
The customer no longer switches to a BI tool
The dashboard lives next to the file. No more Monday CSV or second Metabase login.
The analyst stays in your back office
Single sign-on, same groups. BI opens in the journey you control.
Each account only sees its rows
The customer filter comes from the session, not a manipulable URL parameter. Confidentiality holds.
BI can stay on your side
Controlled hosting, server-side signatures. You keep control of the figures, without exposing Metabase on the internet.
How we ship your Metabase connector
Scoping
Static for a filterable KPI, modular/SSO for an authenticated portal. Cloud or self-host. One mode per case, documented.
JWT
Locked parameters = session IDs, embedding secret server-side only. Group mapping for SSO.
Development
Server-side signing, refresh endpoint for the Agent API (iat < 180 s), never the secret in front, never apiKey in modular prod.
Monitoring
Embedding secret rotation rehearsed in staging. Self-host: private network, SSO, backups. Metabase is not naked on the Internet.
What the Metabase API allows
- REST /api/*
- Session, cards, dashboards, database, permissions. Service account for automation, not an analyst's password.
- Static / guest embedding
- Iframe + JWT signed with the embedding secret. Resource id + locked parameters. No row-level security, no drill-through.
- Modular / SSO embedding
- JWT or SAML, real permissions. Backend endpoint { jwt: "..." } for the SDK. API keys forbidden in production.
- Agent API
- Semantic layer for agents / MCP. JWT iat < 180 s, email and groups claims. Map the user's rights, not an admin key.
Metabase API vocabulary
- Locked parameters
- Values frozen in the static JWT, typically a client_id. From the app session, never from a query string. Without them, static does not isolate rows.
- Embedding secret
- One secret for all static embeds. Theft opens every dashboard. Rotation = every backend. Never in front.
- iat < 180 s
- On the Agent API, the JWT must have an iat under 180 seconds. A one-hour session token is rejected. A refresh endpoint is mandatory.
- Static vs SSO
- Static: locked params, no row-level security, no drill-through. SSO / modular: real permissions, IdP groups. Two products, two quotes.
- X-Metabase-Session
- Session cookie after POST /api/session. Service account, not the analyst. The API key carries the permissions of the key's group, shared by every caller.
- Self-host
- Versions, migrations, Metabase's internal Postgres. This is not a cloud API. Private network, SSO, backups. Metabase is not exposed naked on the Internet.
The real constraints of the Metabase API
Static is not row-level security
Locked params vs SSO permissions. Promising each customer only sees their rows in static without a locked param is a hole. Drill-through in static is impossible.
One embedding secret for everything
Theft opens every embedded dashboard. Rotation touches every backend that signs static JWTs. We rehearse it in staging before production, not on a live portal.
Agent API JWT: 180 seconds
A one-hour session JWT is rejected. Without a refresh endpoint, the assistant dies mid-conversation. This is not optional, and it is not the same token as static embedding.
apiKey in modular prod = no
The docs forbid it. A demo with apiKey does not ship. Self-host: this is operations (versions, Postgres, network), not only an API.
Static embedding or SSO / modular?
Two ways to embed Metabase. The right one depends on who looks at the dashboard and what they are allowed to see.
| Criterion | StaticGuest JWT | SSO / modularReal permissions |
|---|---|---|
| Row isolation | Locked params only | Row-level, IdP groups |
| Drill-through | Impossible | Depends on full / SDK embed |
| Secret | One secret for all static | SSO JWT, not that secret |
| API key | Out of scope | Forbidden in modular prod |
| User session | No, guest | Yes |
| Time to first embed | Shorter | IdP, groups, SDK |
| The right case | Filterable public KPI | Authenticated portal |
We pick one mode per case and document it. Mixing static and SSO on the same screen is the surest way to a filter hole. The secret never leaves the server.
What we measure on a Metabase integration
The other productivity tools
Metabase is combined more often than it is replaced. These options are discussed at scoping.
We combine Metabase with
The stack around Metabase on our projects.
Metabase: your questions
Three decisions, then code. Pick one embed mode per case: static (JWT, locked params) for a filterable KPI, modular/SSO for an authenticated portal. Sign JWTs on the server, IDs from the session, never from a query string. For the Agent API: JWT iat < 180 s and refresh, group mapping, not an admin key. Self-host: private network, SSO, backups. The sensitive part is not the iframe, it is the embedding secret, locked params and the ban on API keys in modular production.
Static: parameters locked in the JWT (client_id from the session), embedding secret server-only. Without a locked param, static does not isolate rows. SSO / modular: real permissions, IdP groups, never an apiKey in production. Do not promise drill-through in static (official docs). A stolen embedding secret opens every static dashboard: rotation rehearsed in staging. That is the test of a BI integrator, not a cosmetic setting.
The docs require an iat under 180 seconds. A one-hour session JWT is rejected. Without a refresh endpoint, the assistant dies mid-conversation. It is not the same token as static embedding. We put refresh in from the prototype, and we never put an admin API key in a user chatbot: permissions are those of the key's group, shared by every caller. A short iat is a product constraint, not a setting we skip.
Yes, and that is often the argument. BI stays in the VPC, the business software signs JWTs. This is not a cloud API: versions, migrations, internal Postgres, SSO, backups, Metabase not naked on the Internet. Embedded Looker or Power BI do not offer the same sovereignty / price ratio. The integration quote includes operations if self-host is in scope, otherwise Metabase cloud, without inventing unpublished hourly quotas.
A first static dashboard filterable by client_id ships in two to three weeks. An SSO / modular portal, Agent API and self-host are closer to six to eight weeks, plus operations if Metabase is not already in place. Duration depends on embed mode, IdP and the semantic model. We scope the perimeter up front and give you a firm estimate before we start, including the embed mode chosen.
A Metabase integration project?
Let's talk. 30 minutes to scope static or SSO, possible self-host, and tell you frankly what locked params will hold.
Discuss my Metabase project