> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Automatic client scope

> Configure customer-specific data filtering for embedded dashboards, filter options, downloads, and scheduled reports.

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](https://docs.usedatabrain.com/developer-docs/helpers/api-reference/token.md).

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

**1. 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](https://docs.usedatabrain.com/guides/datasources/configure-tenants.md) for the customer reference setup.

> [!WARNING]
>
> 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.

**2. 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.

**3. 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](https://docs.usedatabrain.com/developer-docs/helpers/api-reference/token.md):

```json theme={"dark"}
{
  "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.

**4. 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](https://docs.usedatabrain.com/guides/preview-of-dashboards/scheduled-reports-for-end-user.md) for enabling scheduled reports and [email settings](https://docs.usedatabrain.com/guides/preview-of-dashboards/email-settings-for-scheduled-reports.md) 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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.