RBAC: Add available scopes to RBAC docs (#93131)

* update the list with some allowed RBAC scopes * extend the http api docs as well * display without bulletpoints * add prettier ignores
2025-02-25 18:55:37 -06:00 · 2024-09-10 09:50:03 +01:00
parent 831493278f
commit 3197c5de8d
4 changed files with 95 additions and 53 deletions
--- a/docs/sources/developers/http_api/annotations.md
+++ b/docs/sources/developers/http_api/annotations.md
@@ -32,9 +32,12 @@ Annotations are saved in the Grafana database (sqlite, mysql or postgres). Annot

 See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.

-| Action           | Scope                   |
-| ---------------- | ----------------------- |
-| annotations:read | annotations:type:<type> |
+<!-- prettier-ignore-start -->
+| Action             | Scope                                                                                                                                                        |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `annotations:read` | <ul><li>`annotations:*`</li><li>`annotations:type:*`</li><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
+{ .no-spacing-list }
+<!-- prettier-ignore-end -->

 **Example Request**:

@@ -122,9 +125,12 @@ The format for `time` and `timeEnd` should be epoch numbers in millisecond resol
 `POST /api/annotations/graphite`

 **Required permissions**
-| Action             | Scope                         |
-| ------------------ | ----------------------------- |
-| annotations:create | annotations:type:organization |
+
+See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.
+
+| Action               | Scope                           |
+| -------------------- | ------------------------------- |
+| `annotations:create` | `annotations:type:organization` |

 **Example Request**:

@@ -174,9 +180,9 @@ format (string with multiple tags being separated by a space).

 ```http
 HTTP/1.1 200
-
-## Patch Annotation
-
+Content-Type: application/json
+
+```

 ## Patch Annotation

@@ -215,9 +221,12 @@ Updates all properties of an annotation that matches the specified id. To only u
 HTTP/1.1 200
 Content-Type: application/json

-Deletes the annotation that matches the specified id.
-
-**Required permissions**
+```
+
+## Delete Annotation By Id
+
+`DELETE /api/annotations/:id`
+
 Deletes the annotation that matches the specified id.

 **Required permissions**
@@ -260,9 +269,12 @@ This operation currently supports updating of the `text`, `tags`, `time` and `ti

 | Action             | Scope |
 | ------------------ | ----- |
-Accept: application/json
-Content-Type: application/json
-Authorization: Basic YWRtaW46YWRtaW4=
+| `annotations:read` | N/A   |
+
+**Example Request**:
+
+```http
+GET /api/annotations/tags?tag=out HTTP/1.1
 Accept: application/json
 Content-Type: application/json
 Authorization: Basic YWRtaW46YWRtaW4=
@@ -299,9 +311,12 @@ Deletes the annotation that matches the specified id.

 See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.

-| Action             | Scope                   |
-| ------------------ | ----------------------- |
-| annotations:delete | annotations:type:<type> |
+<!-- prettier-ignore-start -->
+| Action               | Scope                                                                                                                                                        |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `annotations:delete` | <ul><li>`annotations:*`</li><li>`annotations:type:*`</li><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
+{ .no-spacing-list }
+<!-- prettier-ignore-end -->

 **Example Request**:

@@ -333,9 +348,9 @@ Find all the event tags created in the annotations.

 See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.

-| Action           | Scope |
-| ---------------- | ----- |
-| annotations:read | N/A   |
+| Action             | Scope |
+| ------------------ | ----- |
+| `annotations:read` | N/A   |

 **Example Request**:

--- a/docs/sources/developers/http_api/dashboard.md
+++ b/docs/sources/developers/http_api/dashboard.md
@@ -43,9 +43,13 @@ Creates a new dashboard or updates an existing dashboard. When updating existing

 See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.

-| Action              | Scope       |
-| ------------------- | ----------- |
-| `dashboards:create` | `folders:*` |
+<!-- prettier-ignore-start -->
+| Action              | Scope                                                                                                   |
+| ------------------- | ------------------------------------------------------------------------------------------------------- |
+| `dashboards:create` | <ul><li>`folders:*`</li><li>`folders:uid:*`</li></ul>                                                   |
+| `dashboards:write`  | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
+{ .no-spacing-list }
+<!-- prettier-ignore-end -->

 **Example Request for new dashboard**:

@@ -164,9 +168,12 @@ Will return the dashboard given the dashboard unique identifier (uid). Informati
 **Required permissions**

 See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
-| `dashboards:delete` | `dashboards:*`<br>`folders:*` |
-
-**Example Request**:
+
+<!-- prettier-ignore-start -->
+| Action              | Scope                                                                                                   |
+| ------------------- | ------------------------------------------------------------------------------------------------------- |
+| `dashboards:delete` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
+{ .no-spacing-list }
 <!-- prettier-ignore-end -->

 **Example Request**:
@@ -220,9 +227,12 @@ Will delete the dashboard given the specified unique identifier (uid).
 DELETE /api/dashboards/uid/cIBgcSjkk/trash HTTP/1.1
 Accept: application/json
 Content-Type: application/json
-HTTP/1.1 200
-Content-Type: application/json
-
+Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
+```
+
+**Example Response**:
+
+```http
 HTTP/1.1 200
 Content-Type: application/json

@@ -267,9 +277,12 @@ Will delete permanently the dashboard given the specified unique identifier (uid

 **Example Response**:

-Status Codes:
-
- **200** – Deleted
+```http
+HTTP/1.1 200
+Content-Type: application/json
+
+```
+
 Status Codes:

 - **200** – Deleted
@@ -314,9 +327,12 @@ Will restore a deleted dashboard given the specified unique identifier (uid).
 Accept: application/json
 Content-Type: application/json
 Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
-
-```http
-HTTP/1.1 200
+```
+
+**Example Response**:
+
+```http
+HTTP/1.1 200
 Content-Type: application/json

 ```
--- a/docs/sources/developers/http_api/dashboard_permissions.md
+++ b/docs/sources/developers/http_api/dashboard_permissions.md
@@ -44,9 +44,12 @@ Gets all existing permissions for the dashboard with the given `uid`.

 See note in the [introduction]({{< ref "#dashboard-permission-api" >}}) for an explanation.

-| Action                        | Scope                                 |
-| ----------------------------- | ------------------------------------- |
-| `dashboards.permissions:read` | `dashboards:uid:*`<br>`folders:uid:*` |
+<!-- prettier-ignore-start -->
+| Action                        | Scope                                                                                                   |
+| ----------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `dashboards.permissions:read` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
+{ .no-spacing-list }
+<!-- prettier-ignore-end -->

 **Example request**:

@@ -123,9 +126,12 @@ Updates permissions for a dashboard. This operation will remove existing permiss
 JSON body schema:

 - **items** - The permission items to add/update. Items that are omitted from the list will be removed.
-```http
-HTTP/1.1 200 OK
-Content-Type: application/json; charset=UTF-8
+
+**Example response**:
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json; charset=UTF-8
 Content-Length: 35

 ```
@@ -192,9 +198,12 @@ Gets all existing permissions for the dashboard with the given `dashboardId`.
 `POST /api/dashboards/id/:dashboardId/permissions`

 Updates permissions for a dashboard. This operation will remove existing permissions if they're not included in the request.
-See note in the [introduction]({{< ref "#dashboard-permission-api" >}}) for an explanation.
-
-| Action                         | Scope                         |
+
+**Required permissions**
+
+See note in the [introduction]({{< ref "#dashboard-permission-api" >}}) for an explanation.
+
+<!-- prettier-ignore-start -->
 | Action                         | Scope                                                                                                   |
 | ------------------------------ | ------------------------------------------------------------------------------------------------------- |
 | `dashboards.permissions:write` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
@@ -275,9 +284,12 @@ Updates permissions for a dashboard. This operation will remove existing permiss

 See note in the [introduction]({{< ref "#dashboard-permission-api" >}}) for an explanation.

-| Action                         | Scope                         |
-| ------------------------------ | ----------------------------- |
-| `dashboards.permissions:write` | `dashboards:*`<br>`folders:*` |
+<!-- prettier-ignore-start -->
+| Action                         | Scope                                                                                                   |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------- |
+| `dashboards.permissions:write` | <ul><li>`dashboards:*`</li><li>`dashboards:uid:*`</li><li>`folders:*`</li><li>`folders:uid:*`</li></ul> |
+{ .no-spacing-list }
+<!-- prettier-ignore-end -->

 **Example request**: