Skip to Content

Embedding Setup

How embedding works

Which part runs where, which credential goes where, and how Databrain keeps each customer's rows apart.

Your backend trades a secret API token for a short-lived guest token. The browser shows the embed with the guest token only.

Sequence diagram: the browser asks your backend; your backend asks the Databrain API to create a guest token and passes it to the browser; the dbn-dashboard element loads cards from the Databrain API, which sends SQL with the client filter to your warehouse and returns only that client's rows as charts.
Your backend trades the API token for a guest token; Databrain adds the client filter to every query.

The parts

PartWhere it livesWhat it does
Data appDatabrain, Data Studio > Data AppsHolds the embeds, API tokens, allowed domains and theme for one product.
EmbedA row in the data app’s Embeds tabOne dashboard or one metric the data app can show.
API tokenYour backend secretsCreates guest tokens for one data app. Never send it to a browser.
Guest tokenThe browser, on the element’s token attributeLets one session show the embeds, as one customer. It expires.
<dbn-dashboard>, <dbn-metric>Your page, from @databrainhq/pluginWeb components that draw the dashboard or metric.

How rows stay apart

  1. Your backend sends clientId, the customer company, when it creates the guest token.
  2. Databrain saves the token with that client, the data app and the params you sent. The browser cannot change them.
  3. For each card, Databrain adds the client filter that matches your tenancy level. For Table it filters on the client column. For Database and Multi-database it uses that customer’s schema or database. Tenancy levels
  4. App filters, row-level settings and table filters from the token are added on top. Multi-tenant access control

Where the embed is allowed to load

The embed loads only on domains in the data app’s Domains list. On any other site it shows UNAUTHORIZED_ORIGIN. The list is shared by every data app of your company.

Which API origin the embed calls

The package calls https://api.usedatabrain.com by default. A self-hosted install sets its own origin with the base-url attribute or window.dbn.baseUrl. The value applies to the whole page, so every embed on a page uses the same origin. Component options reference

The credentials

CredentialMade inUsed for
Data app API tokenData Studio > Data Apps > (app) > API tokensCreating guest tokens and calling the data app APIs for that app.
Service tokenSettings > Developers > Tokens > Service TokensServer-to-server APIs for your whole company, and MCP. Service tokens
Guest tokenYour backend, through the APIThe browser embed only.

On this page