[release-12.3.0] Restructure As code and developer resources (#113969)

Co-authored-by: Roberto Jiménez Sánchez <roberto.jimenez@grafana.com> Co-authored-by: Anna Urbiztondo <anna.urbiztondo@grafana.com>
2025-11-16 19:06:56 +00:00
parent 0898ec6045
commit 047da1442e
96 changed files with 8186 additions and 230 deletions
--- a/docs/sources/developer-resources/api-reference/http-api/folder_permissions.md
+++ b/docs/sources/developer-resources/api-reference/http-api/folder_permissions.md
@@ -0,0 +1,180 @@
+---
+aliases:
+  - ../../../http_api/dashboardpermissions/ # /docs/grafana/next/http_api/dashboardpermissions/
+  - ../../../http_api/folder_permissions/ # /docs/grafana/next/http_api/folder_permissions/
+  - ../../../developers/http_api/folder_permissions/ # /docs/grafana/next/developers/http_api/folder_permissions/
+canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/folder_permissions/
+description: Grafana Folder Permissions HTTP API
+keywords:
+  - grafana
+  - http
+  - documentation
+  - api
+  - folder
+  - permission
+  - permissions
+  - acl
+labels:
+  products:
+    - enterprise
+    - oss
+    - cloud
+title: Folder Permissions HTTP API
+---
+
+# 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](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) 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](#folder-permission-api) for an explanation.
+
+| Action                     | Scope       |
+| -------------------------- | ----------- |
+| `folders.permissions:read` | `folders:*` |
+
+**Example request**:
+
+```http
+GET /api/folders/nErXDvCkzz/permissions HTTP/1.1
+Accept: application/json
+Content-Type: application/json
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+```
+
+**Example Response**
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json; charset=UTF-8
+Content-Length: 551
+
+```
+
+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](#folder-permission-api) for an explanation.
+
+| Action                      | Scope       |
+| --------------------------- | ----------- |
+| `folders.permissions:write` | `folders:*` |
+
+**Example request**:
+
+```http
+POST /api/folders/nErXDvCkzz/permissions
+Accept: application/json
+Content-Type: application/json
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+{
+  "items": [
+    {
+      "role": "Viewer",
+      "permission": 1
+    },
+    {
+      "role": "Editor",
+      "permission": 2
+    },
+    {
+      "teamId": 1,
+      "permission": 1
+    },
+    {
+      "userId": 11,
+      "permission": 4
+    }
+  ]
+}
+```
+
+JSON body schema:
+
+- **items** - The permission items to add/update. Items that are omitted from the list will be removed.
+
+**Example response**:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json; charset=UTF-8
+Content-Length: 35
+
+```
+
+Status Codes:
+
+- **200** - Ok
+- **401** - Unauthorized
+- **403** - Access denied
+- **404** - Dashboard not found
+  "items": [
+    {
+      "role": "Viewer",
+      "permission": 1
+    },
+    {
+      "role": "Editor",
+      "permission": 2
+    },
+    {
+      "teamId": 1,
+      "permission": 1
+    },
+    {
+      "userId": 11,
+      "permission": 4
+    }
+  ]
+}
+```
+
+JSON body schema:
+
+- **items** - The permission items to add/update. Items that are omitted from the list will be removed.
+
+**Example response**:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json; charset=UTF-8
+Content-Length: 35
+
+{"message":"Folder permissions updated","id":1,"title":"Department ABC"}
+```
+
+Status Codes:
+
+- **200** - Ok
+- **401** - Unauthorized
+- **403** - Access denied
+- **404** - Dashboard not found