Add Column-Level Security

Use Column-Level Security to restrict a user's visibility to individual columns within a dataset based on user roles. This keeps sensitive data hidden and reduces the need to maintain separate datasets for each group.

Overview

Organizations often need to protect sensitive information, such as salaries, personally identifiable data, or internal metrics, while allowing the same dataset to be accessed by multiple dashboards for different audiences.

Column-Level Security is implemented through a combination of the following:

• User Roles: Defined in the Qrvey Admin Center.
• Column permissions: Set with an API by adding the accessRoles property to the dataset.
• Widget configuration: User roles are passed in the qvToken used in the widget.

When the widget loads, Qrvey validates the roles in the token and displays the columns that have accessRoles with matching roles. Columns with different accessRoles than those in token will not be displayed.

Note: If a column contains an empty accessRoles property, it will be displayed.

By the end of this guide, you will be able to:

• Define roles for your organization.
• Apply Column-Level Security using an API.
• Pass roles securely in the widget configuration.

Limitations

Column-Level Security applies only to embedded widgets. It is supported for Dashboards and Pixel-Perfect Reports.

Composer and other internal UI components do not apply Column-Level Security. All columns remain visible during design time.

Use Case

When implemented, the widget loads to enable the following:

• A Manager role can only view Revenue and Profit Margin columns.
• An Analyst role can only view the Revenue column.

Each role uses the same dashboard, but the visible data adjusts based on the roles.

Before You Begin

Before setting up Column-Level Security, you should review Qrvey's documentation about embedding widgets using the qvToken. In addition, obtain the following items, permissions, and access:

• At least one dataset available for applying Column-Level Security.
• Administrator access to create user roles in the Admin Center.
• Access to make API calls.

Implementation

Step 1: Create User Roles

Before Column-Level Security can be implemented, roles that are going to be used in the impelentation must exist in Qrvey.

1. Log into the Admin Center using administrator credentials.

2. Go to User Management and select the Roles tab.

3. Create one or more roles that will define column access (for example, Manager, Analyst, or FinanceTeam).

   Caution: Avoid using system roles such as “Administrators” or “Composers” for Column-Level Security. These system roles are meant for platform access, not data visibility control. For more information, see Roles and Permissions.

Step 2: Apply Column-Level Security to Each Dataset

Column-Level Security is configured through API calls. It is not available in Qrvey Composer.

1. Use the Get Dataset endpoint to retrieve the full JSON structure of your dataset.

2. In the JSON response, locate the columns to restrict.

3. Add or edit the accessRoles property for each column, setting it to one of the following:

   • Role name.

   • Role ID (groupid).

   Note: Use one approach (name or ID) in your dataset configuration (accessRoles object) and widget setup (roles object). Avoid mixed configurations.

   For example:

   {
     "columns": [
       {
         "accessRoles": ["Manager"]
       }
     ]
   }

   OR

   {
     "columns": [
       {
         "accessRoles": ["HJ_PQ-qf-e"]
       }
     ]
   }

4. Use the Update Dataset endpoint to update your dataset.

5. Use the Apply Changes to Dataset Definition endpoint to save your changes.

Note: You can add the accessRoles object to individual columns by calling the Set Record Level and Column Level Security endpoint.

Step 3: Pass User Roles in the Widget Configuration

When embedding a widget (for example, a dashboard), declare the user’s roles in the JSON web token (JWT).

Within the config object, use include the qvToken set to the JWT. You can add a single role as a string or add multiple roles in an array.

JWT example:

{
   "appId": "wt5_VpNZa4",
   "userId": "B2dSq6aayx",
   "clientid": "B2dSq6aayx”,
   "roles": [
      “Manager”,
      “Analyst”
   ]
}

Widget configuration example:

var config = {
 domain: "https://yourdomain.qrvey.com",
 dashboardId: “your”-dashboard-id,
 qv_token: token
}

• If your dataset uses role IDs for Column-Level Security, pass the corresponding IDs in the roles array.
• If your dataset uses role names, pass their names.

For more information, see Dashboard Widget.

Troubleshooting

The following table displays common issues encountered when setting up column-level security and steps used to resolve them.

Issue	Cause	Solution
Columns are not being hidden as expected.	Column-Level Security roles are not correctly applied to the dataset or missing in the widget configuration.	- Verify that the accessRoles property exists for the target column. - Verify that your widget configuration includes the correct roles (matching IDs or names).
Widget shows errors or fails to load.	Mismatch between role name and role ID systems.	Make sure the same format (ID or name) is used for both dataset configuration and widget embedding.
Changes not reflected.	Cached token or outdated configuration.	Regenerate the qvToken, clear your cache, and reload the embedded widget.

Best Practices

• Define user roles early and assign them meaningful, descriptive names.
• Apply Column-Level Security in the API after roles are finalized.
• Use consistent identifiers (either IDs or names) in your setup.
• Generate widget configurations securely on the backend.
• Test Column-Level Security behavior for different roles before deploying to production.
• Avoid excess columns restrictions that might affect chart logic or aggregations.