Embed Portal - Row-level Settings

BETA FEATURE

This is a Beta feature. The documentation and feature may change rapidly. You can request Beta access and try it out.

Introduction

Holistics supports setting data permissions via row-level permissions to control which data users can access in your embed portals.

Row-level permissions have two key parts:

1. Define permissions based on user attributes - You specify which dataset fields should be restricted and which user attributes to match against
2. Control data access through attribute values - Different users receive different values for these attributes, which determines which specific data they can see

Example: A user with region = 'US' will only see data where the region field equals 'US', while a user with region = 'EU' will only see European data.

This approach allows you to create a single embed portal that serves multiple users or organizations while ensuring each user only sees their authorized data.

How to set up row-level permission in embed portal

Follow these four steps to configure row-level permissions that control which data each user can access:

1. Define user attributes in Holistics (e.g., region)
2. Set up permissions in your dataset to match these attributes with specific fields
3. Pass user attribute values from your backend in the embed payload

1. Define user attribute

Before using user attributes in dataset permissions, you must define them in Holistics. See: User Attributes Documentation

2. Define permission in the dataset

In this step, you need to specify which specific field in the dataset you want to apply the row-level permission on:

Dataset sales_data {
  // ... your models and dimensions ...  
  permission regional_access {
    field: r(orders.region) // field in dataset that you want to apply permission
    operator: 'matches_user_attribute'
    value: 'region' // user attribute 
  }
}

The code above defines a regional_access permission, which ensures that embed users only see data corresponding to their assigned region attribute.

Key points:

• field: reference the field in your dataset that you want to restrict
• operator: must be matches_user_attribute to define row-level permission based on user attribute
• value: user attribute name you defined in the previous step

For more details, please refer to our doc about row-level permission as-code

3. Pass user attributes from the backend via the embed payload

When generating embed tokens, include user-specific attribute values to enforce the row-level permissions you've configured.

// Basic embed payload
const embed_payload = {
  user_attributes: {
    region: ['US'],
  },
};

Result Now this embed portal will only show rows which have: orders.region is US

Advanced configurations

Bypass permissions with __ALL__

You can bypass specific row-level permissions by setting the user attribute to __ALL__:

const embed_payload = {
  user_attributes: {
    region: '__ALL__',  // This will let this user view all data regardless of region  
    company_id: [456],    // Still applies company_id restrictions
  }
}

Result the user will see data from all regions.

This will be useful for cases where you want a specific user or a group of users to see all data (like CEO, regional manager, etc.)

Define default values for user attributes

You can define default user attribute values at the embed portal level to simplify your implementation and reduce repetitive code. This is particularly useful when:

• All users share common restrictions - For example, an embed portal where all users should only see US data
• You want to bypass certain permissions by default - For example, excluding internal filtering (like employee_id) for external users
• You need fallback values - Providing sensible defaults that can be overridden when needed

Setting default attributes

Define default user attributes directly in your embed portal configuration:

EmbedPortal customer_analytics {
  objects: [
    sales_data,        // dataset
    sales_performance  // dashboard
  ],

  default_user_attributes {
    region: ['US'],           // All users see US data by default
    employee_id: '__ALL__'    // Bypass employee-level filtering by default
  }
}

With these defaults:

• All users automatically see US region data
• Employee-level permissions are bypassed (useful for customer-facing portals)
• No need to include these attributes in every embed payload

Override behavior

Default values can be overridden by passing specific values in the embed payload. The precedence is:

Embed payload values > Portal default values

Example:

// Embed portal configuration
EmbedPortal customer_analytics {
  objects: [
    sales_data,
    sales_performance
  ],
  default_user_attributes: {
    region: ['US'],
    employee_id: '__ALL__'
  }
}

// Embed payload for a specific user
const embed_payload = {
  user_attributes: {
    region: ['EU']    // Override default: this user sees EU data
    // employee_id not specified, so uses default '__ALL__'
  }
}

Result: This user will see EU data (overridden from embed payload) with all employee data (default value in embed portal).