Skip to Content

Architecture

Embedding architecture

How your app, your backend and Databrain work together to show each customer their own dashboard.

How embedding works

You put a Databrain dashboard or metric inside your product. Your backend trades a secret API token for a short-lived guest token. Your page shows the embed with the guest token only, and Databrain returns only the rows of that customer.

Sequence diagram: the browser opens the analytics page, your backend sends the API token and clientId to Databrain, Databrain returns a guest token, the backend passes it to the browser, dbn-dashboard loads with the token, Databrain queries your warehouse with the customer filter and returns only that customer's rows as charts
The guest token flow. Blue steps carry the guest token. Your API token never leaves your backend.

The parts

PartWhere it livesWhat it does
Data appData Studio > Data AppsHolds the embeds, API tokens, allowed domains and theme for one product. See Data apps.
EmbedThe data app’s Embeds tabOne dashboard or one metric the data app can show.
API tokenYour backend secretsCreates guest tokens for one data app. It is shown once. 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 the @databrainhq/plugin packageWeb components that draw the dashboard or metric.
Data app Overview with the Go-live readiness checklist and the Installation card showing the guest token request and the dbn-dashboard snippet
A data app's Overview shows what is ready to go live and the two install steps: create a guest token, render the embed.

How each customer sees only their rows

  1. Your backend sends clientId, the customer’s ID in your product, when it creates the guest token.
  2. Databrain saves the token with that client and the data app. The browser cannot change them.
  3. For every query, Databrain adds the filter that matches your tenancy model:
    • Table: a filter on the client column of each table.
    • Database or Multi-database: that customer’s own schema or database.
  4. Extra filters you put in the guest token, such as app filters, are added on top.

The clientId must exist in your data: a value in the client column for Table, or the schema or database name for Database and Multi-database. Otherwise Databrain refuses the token with CLIENT_ID_ERROR. If no workspace of the data app has tenancy set, the token is not scoped to a customer at all.

Set tenancy on the datasource or, better, on the datamart before you embed. A datamart’s tenancy wins over the datasource’s.

Where the embed can load

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

Self-hosted Databrain

The package calls https://api.usedatabrain.com by default. A self-hosted install points the embed at its own API with the base-url attribute. See Component options.

Next steps