Manage Workspace Permissions

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

  • permissions are tied to a specific 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 Build a Workspace Hierarchy.

Supported Permissions

The following permissions are applicable to a workspace object:

  • VIEW

    A user can view dashboards that have been shared to them.

  • ANALYZE and EXPORT

    Either permission gives you the same level of access as the VIEW permission. Additionally:

    • With the ANALYZE permission, a user can also create, edit or delete dashboards and visualizations, and view the LDM and metrics.

    • With the EXPORT permission, a user can view and export dashboards to PDF files and tabular data from visualizations to XLSX and CSV files.

    The EXPORT permission has more granular sub-permissions:

    • With the EXPORT_PDF permission, a user can only view and export dashboards to PDF files.

    • With the EXPORT_TABULAR permission, a user can only view and export tabular data from visualizations to XLSX and CSV files.

  • MANAGE

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

Set Permissions For a Workspace

Workspaces come with the API endpoint /api/v1/actions/workspaces/<workspace_id>/managePermissions/ that allows you to set permissions for a particular workspace without having to re-declare the entire workspace layout using a declarative API. Note that you need the Organization.MANAGE permission or the Workspace.MANAGE hierarchyPermission to use this API endpoint.

You can also set permissions using declarative API endpoints /api/v1/layout/workspaces or /api/v1/layout/organization. Note that you need the Organization.MANAGE permission to use these API endpoints.

Steps:

  1. Define new permissions in json format, for example:

    [
        {
            "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"
            ]
        }
    ]
    

    Use the permissions definition for users that should be able to access only the specific workspace.

    Use the hierarchyPermissions definition for users that should be able to access not only the specific workspace, but also its child workspaces.

    You may, but do not have to use both types of these permission definitions.

  2. Update the workspace permissions 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