Embed portal - Data Permission 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

The Permission Flow:

1. Define user attributes in Holistics (e.g., region, company_id)
2. Set up permissions in your dataset to match these attributes with specific fields
3. Portal Permission Settings (optional) - Set default user attributes for all users
4. Pass user attribute values from your backend in the embed payload

1. Define User Attributes First

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: ref('orders', 'region') // field in dataset that you want to apply permission
    operator: 'matches_user_attribute'
    value: 'region' // user attribute 
  }
  permission company_access {
    field: ref('orders', 'company_id') // field in dataset that you want to apply permission
    operator: 'matches_user_attribute'
    value: 'company_id' // user attribute 
  }
}

Key Points:

• The value must match a user attribute name you defined in Settings
• The field should reference the field in your dataset that you want to restrict

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

3. Portal Permission Settings (optional)

You can configure default permission settings directly in your Embed Portal. These default user attributes can be overridden in the embed token:

EmbedPortal customer_analytics {
  objects: [
    sales_data,        // dataset
    sales_performance  // dashboards  
  ],
  // Optional: Set default user attributes (can be overridden in embed token)
  default_user_attributes {
    region: 'US'
  }
}

4. Passing user attributes from the backend via the embed payload

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

Now this embed portal will show rows which have: orders.region is US and orders.company_id is 456

Bypassing 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
    }
}

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.)