Folder Permissions API

This API can be used to update/get the permissions for a folder.

Permissions with folderId=-1 are the default permissions for users with the Viewer and Editor roles. Permissions can be set for a user, a team or a role (Viewer or Editor). Permissions cannot be set for Admins - they always have access to everything.

The permission levels for the permission field:

  • 1 = View
  • 2 = Edit
  • 4 = Admin

If you are running Grafana Enterprise, for some endpoints you’ll need to have specific permissions. Refer to Role-based access control permissions for more information.

Get permissions for a folder

GET /api/folders/:uid/permissions

Gets all existing permissions for the folder with the given uid.

Required permissions

See note in the introduction for an explanation.

ActionScope
folders.permissions:readfolders:*

Example request:

  1. GET /api/folders/nErXDvCkzz/permissions HTTP/1.1
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

Example Response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. Content-Length: 551
  5. [
  6.   {
  7.     "id": 1,
  8.     "folderId": -1,
  9.     "created": "2017-06-20T02:00:00+02:00",
  10.     "updated": "2017-06-20T02:00:00+02:00",
  11.     "userId": 0,
  12.     "userLogin": "",
  13.     "userEmail": "",
  14.     "teamId": 0,
  15.     "team": "",
  16.     "role": "Viewer",
  17.     "permission": 1,
  18.     "permissionName": "View",
  19.     "uid": "nErXDvCkzz",
  20.     "title": "",
  21.     "slug": "",
  22.     "isFolder": false,
  23.     "url": ""
  24.   },
  25.   {
  26.     "id": 2,
  27.     "dashboardId": -1,
  28.     "created": "2017-06-20T02:00:00+02:00",
  29.     "updated": "2017-06-20T02:00:00+02:00",
  30.     "userId": 0,
  31.     "userLogin": "",
  32.     "userEmail": "",
  33.     "teamId": 0,
  34.     "team": "",
  35.     "role": "Editor",
  36.     "permission": 2,
  37.     "permissionName": "Edit",
  38.     "uid": "",
  39.     "title": "",
  40.     "slug": "",
  41.     "isFolder": false,
  42.     "url": ""
  43.   }
  44. ]

Status Codes:

  • 200 - Ok
  • 401 - Unauthorized
  • 403 - Access denied
  • 404 - Folder not found

Update permissions for a folder

POST /api/folders/:uid/permissions

Updates permissions for a folder. This operation will remove existing permissions if they’re not included in the request.

Required permissions

See note in the introduction for an explanation.

ActionScope
folders.permissions:writefolders:*

Example request:

  1. POST /api/folders/nErXDvCkzz/permissions
  2. Accept: application/json
  3. Content-Type: application/json
  4. Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
  5. {
  6.   "items": [
  7.     {
  8.       "role": "Viewer",
  9.       "permission": 1
  10.     },
  11.     {
  12.       "role": "Editor",
  13.       "permission": 2
  14.     },
  15.     {
  16.       "teamId": 1,
  17.       "permission": 1
  18.     },
  19.     {
  20.       "userId": 11,
  21.       "permission": 4
  22.     }
  23.   ]
  24. }

JSON body schema:

  • items - The permission items to add/update. Items that are omitted from the list will be removed.

Example response:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. Content-Length: 35
  5. {"message":"Folder permissions updated","id":1,"title":"Department ABC"}

Status Codes:

  • 200 - Ok
  • 401 - Unauthorized
  • 403 - Access denied
  • 404 - Dashboard not found