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 isdashboards
.workspace_object_id
: This corresponds to theresource_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 to01eec14769f616949d7a44244a53ed10
.
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"
}
]
}