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.
The parts
| Part | Where it lives | What it does |
|---|---|---|
| Data app | Data Studio > Data Apps | Holds the embeds, API tokens, allowed domains and theme for one product. See Data apps. |
| Embed | The data app’s Embeds tab | One dashboard or one metric the data app can show. |
| API token | Your backend secrets | Creates guest tokens for one data app. It is shown once. Never send it to a browser. |
| Guest token | The browser, on the element’s token attribute | Lets one session show the embeds as one customer. It expires. |
<dbn-dashboard>, <dbn-metric> | Your page, from the @databrainhq/plugin package | Web components that draw the dashboard or metric. |

How each customer sees only their rows
- Your backend sends
clientId, the customer’s ID in your product, when it creates the guest token. - Databrain saves the token with that client and the data app. The browser cannot change them.
- 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.
- 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
- Embed a dashboard: the full steps with code.
- How embedding works: credentials, origins and limits in detail.