Skip to Content

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 levelclientIdDatabrain scopes by
TableA value in the customer table’s Primary key columnRows where the client column equals clientId. In SQL, client_id_variable becomes clientId.
DatabaseThe tenant’s schema nameThe tenant’s schema
Multi-databaseThe tenant’s database nameThe 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

FieldScope
params.tableAppFiltersEvery query that reads the table, on every dashboard and metric
params.dashboardAppFiltersOne dashboard filter. See Dashboard App Filter.
params.appFiltersOne metric filter. See Metric App Filter.
params.rlsSettingsRow 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.com allows every subdomain. See Whitelist domains.
  • params.allowedEmbeds. The dashboard IDs this token can open. Other dashboards return UNAUTHORIZED.
  • 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

  1. Create tokens for two clients, A and B, with known totals.
  2. Open the same dashboard with each token. Each shows only its own total.
  3. Download a CSV and open underlying data with each token. Each shows only its own rows.
  4. 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.