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.

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

  • MANAGE

    Covers the 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.

Workspace Permissions

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.

Data Sources
Dashboard