Automatic client scope

Automatic client scope filters data for the customer identified by your application’s guest token. Configure the customer identifier on each relevant datamart table, then enable automatic scope when your backend creates the token. For example, Acme and Northstar can use the same embedded sales dashboard. With orders.customer_id mapped as the client column, Acme’s session queries Acme’s orders and Northstar’s session queries Northstar’s orders.

What changed

Custom SQL filtering now preserves more existing query structures, including casts, aliases, and grouped conditions. Saved custom SQL metrics are read-only for embedded end users; workspace authors maintain their SQL.

Before you start

You need:

A datamart configured for Table tenancy, linked to the workspace and embedding configuration you use.
A customer reference table with a primary key and customer-name column.
A client-column mapping on every table that contains customer-specific data.
A Data App and an embedded dashboard or metric.
Access to your application’s backend code that creates guest tokens.

Automatic client scope is optional and must be enabled in the guest token. Database- and schema-based tenancy continue to use their existing tenancy configuration.

Set it up

Configure customer identifiers in your datamart

Open your datamart’s tenancy settings. For Table tenancy, select the customer reference table and configure Primary Key, Primary Key Type, and Customer Name.Under Client Column Mapping, select the column that identifies the customer in each customer-specific table. Save your changes with Update when editing an existing configuration.

Table	Client column	Purpose
`customers`	`id`	Identifies the customer
`orders`	`customer_id`	Restricts orders to that customer
`invoices`	`customer_id`	Restricts invoices to that customer

The value your application sends as clientId must match these identifiers. See Configure tenants for the customer reference setup.

A table without a client-column mapping remains unfiltered by automatic client scope. Leave a mapping blank only for intentionally shared data, such as a public country lookup table. If no tables are mapped, automatic scope adds no customer filters.

Check the embedding configuration

Confirm that your workspace and embedding configuration use the intended datamart. Client-column mappings displayed in sharing and access settings are read-only; change them in the datamart configuration.

Enable automatic scope when creating the guest token

From your application’s backend, add isAllowAutoClientScope: true inside params.accessPermissions. Set clientId from the signed-in user’s authorized customer account.Example request body for the Create guest token API:

{
  "dataAppName": "Customer Analytics",
  "clientId": "acme-001",
  "params": {
    "accessPermissions": {
      "isAllowAutoClientScope": true
    }
  }
}

Replace the example names and identifier with your own values. Keep any other token parameters your integration needs. The flag belongs under params.accessPermissions, rather than the top-level permissions object.Use the returned guest token in your existing embed integration. Generate a new token with this setting to enable automatic scope for a session. Keep your Data App API key on your backend.

Verify with two customer accounts

Load the same dashboard with a token for Acme, then with a separate token for Northstar. Check that each session returns the expected customer’s data.Also check the features you offer: table-backed filter dropdowns, CSV downloads, underlying data, dashboard download archives, and scheduled report attachments. Compare them with the dashboard’s customer context.

Use it day to day

Customers use the embedded dashboard as usual. They can adjust permitted filters and download data when those actions are enabled. Automatic scope applies in the background; customers do not select their own tenant in the embed. To schedule delivery, open Scheduled Reports in the embedded dashboard when enabled. Enter the Subject Line and Send to addresses, choose Charts to Attach, then set the frequency, delivery time, and timezone. Enable Share Download file and select a Download File Format if you want downloadable report files. Save the schedule. Embedded schedules retain the guest-token and embed context used to create them. Their downloadable data uses the token’s customer scope. For an existing schedule, check its saved token and embed context before relying on automatic scope; changing your token-generation code alone does not update the token already associated with that schedule. See Scheduled reports for end users for enabling scheduled reports and email settings for delivery setup.

Existing SQL and other access rules

Existing customer placeholders: Saved SQL that already uses a client equality condition such as WHERE customer_id = 'client_id_variable' keeps that substitution path. Automatic scope does not add another set of customer filters to that query. Keep the existing customer conditions complete and correct.
Custom SQL without a placeholder: With automatic scope enabled, Databrain uses the datamart mappings to filter supported queries. A query that needs scoping but cannot be safely scoped returns an error. Some custom SQL result-based filter configurations still require an explicit customer placeholder; validate these filters with your query.
End-user SQL editing: Embedded end users cannot edit saved custom SQL metrics. Ask a workspace author to change the SQL. Permitted filter interactions remain separate from SQL editing.
Additional restrictions: Existing row-level security, application filters, and action permissions still apply. Automatic scope does not grant permission to download, view underlying data, or send reports.

Troubleshooting

What you see	What to check
Customer-specific data is not filtered	Confirm that the session’s token includes `params.accessPermissions.isAllowAutoClientScope: true`, the tenancy is Table, and the queried tables have client-column mappings.
No rows for a customer	Check that `clientId` matches the stored customer identifier and its datatype. Review any additional dashboard, metric, application, or row-level filters.
A scope or query error	Check the datamart, workspace, embed, and token belong together. Custom integrations must retain the correct embed context in query and download requests. Review the query if its structure cannot be scoped.
A filter fails on a custom SQL metric	Check the saved SQL source and its customer placeholder, especially for filters based on SQL result columns.
A report fails or uses an old configuration	Check the schedule’s saved guest token, expiry, embed, and customer context. Update the schedule through your integration as needed.
An end user cannot edit a SQL metric	This is expected. A workspace author must edit custom SQL.

Onboarding

Data Sources

Datamarts

Workspaces

Dashboards

Metrics

Visualizations

Filters

Theming & Customization

Data Apps

Advanced Features

Reports & Scheduling

Automatic client scope

What changed

Before you start

Set it up

Use it day to day

Existing SQL and other access rules

Troubleshooting

​What changed

​Before you start

​Set it up

​Use it day to day

​Existing SQL and other access rules

​Troubleshooting

What changed

Before you start

Set it up

Use it day to day

Existing SQL and other access rules

Troubleshooting