Manage Workspace Permissions

Workspace permissions specify what users can do within a workspace, covering a range of activities from simply viewing dashboards to managing the workspace’s entire logical data model.

Permissions and Hierarchy Permissions

Workspace permissions can be assigned using two types of permission definitions:

• permissions are tied to an individual workspace and define what a user can do with that one specific workspace.

• hierarchyPermissions are tied to a specific workspace and define what a user can do with that specific workspace and all of its child workspaces. For more information on workspace hierarchies, see the Build a Workspace Hierarchy section.

Supported Permissions

The following permissions are applicable to a workspace object:

• VIEW

  Allows the user to view dashboards that have been shared to them.

  • CREATE_FILTER_VIEW

    This permission subset allows the user to save the states of dashboard filters. It must be applied alongside the VIEW permission.

• ANALYZE

  Allows users to not only view but also create, edit, or delete dashboards and visualizations, alongside viewing the Logical Data Model (LDM) and metrics.

• EXPORT

  Enables users to view dashboards and export them to PDF files, as well as export visualization data to XLSX and CSV files.

  Further distinctions within the EXPORT permission include:

  • EXPORT_PDF: Specifically for viewing and exporting dashboards as PDF files.

  • EXPORT_TABULAR: Enables viewing and exporting visualization data to XLSX and CSV formats.

• CREATE_AUTOMATION allows workspace users to create new alerts and scheduled exports on dashboards.

• AI_USE_ASSISTANTgrants permission to use the AI Assistant feature. This permission is required in addition to others (such as ANALYZE and higher) for users to be able to fully interact with and save visualizations generated by the Assistant.

• MANAGE

  Covers the VIEW, CREATE_FILTER_VIEW, ANALYZE and EXPORT permissions. Additionally, a user can create, edit or delete the logical data model and metrics, and access all dashboards and edit their dashboard permissions without limitations.

  Additional Permissions May Be Required

  To be able to fully work with the LDM, a user also requires at least the `USE` permission for the data source that the workspace is connected to. See the [Manage Data Sources Permissions](../set-permissions-for-data-source/) section for details.

Set Permissions For a Workspace

Workspaces can have their permissions configured through specific API endpoints, providing a flexible approach to access control.

To directly set permissions for an individual workspace, use the /api/v1/actions/workspaces/<workspace_id>/managePermissions/ endpoint. This method does not require redefining the entire workspace layout. Access to this endpoint requires either Organization.MANAGE permission or Workspace.MANAGE hierarchyPermission.

Alternatively, you can set permissions using the declarative API through the following endpoints:

• /api/v1/layout/workspaces
• /api/v1/layout/organization

These endpoints offer a broader scope of permissions management but require the Organization.MANAGE permission for access.

Steps:

Follow these steps to update your workspace permissions through an API call:

1. Define the Permissions in a JSON File

   [
       {
           "assigneeIdentifier": {
               "id": "<user_group_id>",
               "type": "userGroup"
           },
           "hierarchyPermissions": [
               "MANAGE"
           ]
       },
       {
           "assigneeIdentifier": {
               "id": "<user_group_2_id>",
               "type": "userGroup"
           },
           "permissions": [
               "ANALYZE"
           ],
           "hierarchyPermissions": [
               "EXPORT_PDF"
           ]
       },
       {
           "assigneeIdentifier": {
               "id": "<user_id>",
               "type": "user"
           },
           "permissions": [
               "EXPORT"
           ]
       }
   ]
   

2. Update the Workspace Permissions

   Update the workspace permissions with your json file using the following API call:

   curl -H "Authorization: Bearer $API_TOKEN" \
       -H "Content-Type: application/json" \
       -X POST \
       $HOST_URL/api/v1/actions/workspaces/<workspace_id>/managePermissions/ -d @<your_workspace_permissions>.json
   

Permissions JSON Structure

• Permissions Definition

  • Use the permissions definition if you want to give a user access to a single, specific workspace.

  • Use the hierarchyPermissions definition if you want to give a user access to a workspace and all its subordinated child workspaces.

  It’s optional to use both permissions types simultaneously, depending on your access control needs.

• Assignee

  An assignee refers to either a user or a user group, identified by their id and specified by type within the permissions setup.

• Name

  The permission name (e.g. MANAGE) within this structure dictates the level of access, mapping to specific actions that are otherwise restricted.