Manage dashboard permissions using the Workspace API

This tutorial demonstrates how to manage dashboard permissions using the Workspace API. Each step includes a sample request and response and explanations about how to use the API tools and properties together.

Prerequisites

• You need a personal access token to connect with your workspace. See Databricks personal access token authentication.

• You need the workspace ID of the workspace you want to access. See Workspace instance names, URLs, and IDs

• Familiarity with the Databricks REST API reference.

Path parameters

Each endpoint request in this article requires two path parameters, workspace_object_type and workspace_object_id.

• workspace_object_type: For AI/BI dashboards, the object type is dashboards.

• workspace_object_id: This corresponds to the resource_id associated with the dashboard. You can use the GET /api/2.0/workspace/list or GET /api/2.0/workspace/get-status to retrieve that value. It is a 32-character string similar to 01eec14769f616949d7a44244a53ed10.

See Step 1: Explore a workspace directory for an example of listing workspace objects. See GET /api/2.0/workspace/list for details about the the Workspace List API.

Get workspace object permission levels

This section uses the Get workspace object permission levels endpoint to get the permission levels that a user can have on a dashboard. See GET /api/workspace/workspace/getpermissionlevels.

In the following example, the request includes sample path parameters described above. The response includes the permissions that can be applied to the dashboard indicated in the request.

GET /api/2.0/permissions/dashboards/01eec14769f616949d7a44244a53ed10/permissionLevels

Response:
{
        "permission_levels": [
                {
                        "permission_level": "CAN_READ",
                        "description": "Can view the Lakeview dashboard"
                },
                {
                        "permission_level": "CAN_RUN",
                        "description": "Can view, attach/detach, and run the Lakeview dashboard"
                },
                {
                        "permission_level": "CAN_EDIT",
                        "description": "Can view, attach/detach, run, and edit the Lakeview dashboard"
                },
                {
                        "permission_level": "CAN_MANAGE",
                        "description": "Can view, attach/detach, run, edit, and change permissions of the Lakeview dashboard"
                }
        ]
}

Get workspace object permission details

The Get workspace object permissions endpoint gets the assigned permissions on a specific workspace object. See GET /api/workspace/workspace/getpermissions.

The following example shows a request and response for the dashboard in the previous example. The response includes details about the dashboard and users and groups with permissions on the dashboard. Permissions on this object have been inherited for both items in the access_control_list portion of the response. In the first entry, permissions are inherited from a folder in the workspace. The second entry shows permissions inherited by membership in the group, admins.

GET /api/2.0/permissions/dashboards/01eec14769f616949d7a44244a53ed10

Response:
{
"object_id": "/dashboards/490384175243923",
"object_type": "dashboard",
"access_control_list": [
  {
  "user_name": "first.last@example.com",
  "display_name": "First Last",
  "all_permissions": [
        {
          "permission_level": "CAN_MANAGE",
          "inherited": true,
          "inherited_from_object": [
                        "/directories/2951435987702195"
                ]
        }
]
},
{
"group_name": "admins",
"all_permissions": [
        {
                "permission_level": "CAN_MANAGE",
                "inherited": true,
                "inherited_from_object": [
                        "/directories/"
                ]
        }
]
}
]
}

Set workspace object permissions

You can set permissions on dashboards using the Set workspace object permissions endpoint. See PUT /api/workspace/workspace/setpermissions.

The following example gives CAN EDIT permission to all workspace users for the workspace_object_id in the PUT request.

PUT /api/2.0/permissions/dashboards/01eec14769f616949d7a44244a53ed10

Request body:

{
"access_control_list": [
{
        "group_name": "users",
        "permission_level": "CAN_EDIT"
}
]
}

For AI/BI dashboards, you can use the group All account users to assign view permission to all users registered to the Databricks account. See Share a published dashboard.

Update workspace object permissions

The Update workspace object permissions endpoint performs functions similarly to the Set workspace object permissions endpoint. It assigns permissions using a PATCH request instead of a PUT request.

See PATCH /api/workspace/workspace/updatepermissions.

PATCH /api/2.0/permissions/dashboards/01eec14769f616949d7a44244a53ed10

Request body:

{
  "access_control_list": [
    {
      "group_name": "account userS",
      "permission_level": "CAN_VIEW"
    }
  ]
}