From aeb57f671bfacf3cf30eddc24e1b9f489c17a6b8 Mon Sep 17 00:00:00 2001
From: Hugo Kiyodi Oshiro <hugo.oshiro@grafana.com>
Date: Thu, 13 Feb 2025 16:53:03 +0100
Subject: [PATCH] Docs: Improve instructions to change basic roles (#100586)

---
 .../plan-rbac-rollout-strategy/index.md        | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/docs/sources/administration/roles-and-permissions/access-control/plan-rbac-rollout-strategy/index.md b/docs/sources/administration/roles-and-permissions/access-control/plan-rbac-rollout-strategy/index.md
index 09c2fc4c3d4..e04c2fcecf2 100644
--- a/docs/sources/administration/roles-and-permissions/access-control/plan-rbac-rollout-strategy/index.md
+++ b/docs/sources/administration/roles-and-permissions/access-control/plan-rbac-rollout-strategy/index.md
@@ -369,9 +369,11 @@ Here are two ways to achieve this:
 
   # Update the role
   curl -H 'Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt' -H 'Content-Type: application/json' \
-    -X PUT-d @/tmp/basic_viewer.json '<grafana_url>/api/access-control/roles/basic_viewer'
+    -X PUT -d @/tmp/basic_viewer.json '<grafana_url>/api/access-control/roles/basic_viewer'
   ```
 
+  The token that is used in this request is the [service account token](ref:service-accounts).
+
 - Or use the `role > from` list and `permission > state` option of your provisioning file:
 
   ```yaml
@@ -394,6 +396,20 @@ Here are two ways to achieve this:
           state: 'present'
   ```
 
+  If your goal is to remove an access to an app you should remove it from the role and update it. For example:
+
+  ```bash
+  # Fetch the role, modify it to remove permissions to kentik-connect-app and increment role version
+  curl -H 'Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt' \
+    -X GET '<grafana_url>/api/access-control/roles/basic_viewer' | \
+    jq 'del(.created)| del(.updated) | del(.permissions[].created) | del(.permissions[].updated) | .version += 1' | \
+    jq 'del(.permissions[] | select (.action == "plugins.app:access" and .scope == "plugins:id:kentik-connect-app"))'
+
+  # Update the role
+  curl -H 'Authorization: Bearer glsa_kcVxDhZtu5ISOZIEt' -H 'Content-Type: application/json' \
+    -X PUT -d @/tmp/basic_viewer.json '<grafana_url>/api/access-control/roles/basic_viewer'
+  ```
+
 ### Manage user permissions through teams
 
 In the scenario where you want users to grant access by the team they belong to, we recommend to set users role to `No Basic Role` and let the team assignment assign the role instead.