Authentication & Security
Control access for each tenant
Make each customer see only their own data, and limit what each person inside a customer sees.
Access has three layers. Tenancy picks the customer. Token filters narrow rows inside that customer. Domains and dashboards limit where and what can load.
Before you start
- The datasource has a Tenancy level: Table, Database or Multi-database. See Tenancy model.
Layer 1: the tenant (clientId)
clientId is your customer company, not a person. Your backend sets it from the signed-in user’s session.
| Tenancy level | clientId | Databrain scopes by |
|---|---|---|
| Table | A value in the customer table’s Primary key column | Rows where the client column equals clientId. In SQL, client_id_variable becomes clientId. |
| Database | The tenant’s schema name | The tenant’s schema |
| Multi-database | The tenant’s database name | The tenant’s database |
Without a tenancy level, clientId is still required but does not scope data.
On table tenancy, "accessPermissions": { "isAllowAutoClientScope": true } adds client column = clientId to every datamart table with a client column. A query it cannot scope is refused.
Layer 2: rows inside a tenant
| Field | Scope |
|---|---|
params.tableAppFilters | Every query that reads the table, on every dashboard and metric |
params.dashboardAppFilters | One dashboard filter. See Dashboard App Filter. |
params.appFilters | One metric filter. See Metric App Filter. |
params.rlsSettings | Row level security filters saved in the workspace, by name |
Example for a person who may see only the East region:
{
"clientId": "acme-corp",
"dataAppName": "Customer Analytics",
"params": {
"userIdentifier": "jane@acme.example",
"tableAppFilters": [
{ "tableName": "public.orders", "columnName": "region", "values": ["East"] }
]
}
}Layer 3: where and what can load
- Whitelisted domains. Only pages on these domains can load the embed.
*.example.comallows every subdomain. See Whitelist domains. params.allowedEmbeds. The dashboard IDs this token can open. Other dashboards returnUNAUTHORIZED.params.hideDashboardMetrics. Metrics to hide on a dashboard for this token.
clientId and userIdentifier
params.userIdentifier is the person. It owns metrics they create and their private items. It never scopes rows. Two people with the same clientId see the same rows unless you add Layer 2 filters.
Test it
- Create tokens for two clients, A and B, with known totals.
- Open the same dashboard with each token. Each shows only its own total.
- Download a CSV and open underlying data with each token. Each shows only its own rows.
- Open the embed from a domain that is not whitelisted. It returns 403
UNAUTHORIZED_ORIGIN.
If something goes wrong
- 400
CLIENT_ID_ERROR: “Client ‘<id>’ was not found in data app ‘<name>’.” On table tenancy, use a value from the client column. On database tenancy, use the schema or database name. If the tenant is new, run Sync schema first. - 400
RLS_SETTINGS_PARAM_ERROR: “Invalid rls filter name: <name>”. No RLS filter has this name in the data app’s workspaces. - 403
UNAUTHORIZED_ORIGIN. Add the page’s domain to the whitelisted domains.
Related: Security.