--- title: "Manage Grafana RBAC roles | Grafana Cloud documentation" description: "Learn how to view permissions associated with roles, create custom roles, and update and delete roles in Grafana." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Manage RBAC roles > Note > > Available in [Grafana Enterprise](/docs/grafana/next/introduction/grafana-enterprise/) and [Grafana Cloud](/docs/grafana-cloud/). This section includes instructions for how to view permissions associated with roles, create custom roles, and update and delete roles. ## View basic role definitions You can retrieve the full definition of a basic role, including all associated permissions, using the API or by navigating directly to the endpoint URL in your browser while logged in as an Admin. ### Using the API To get the definition of a basic role: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash GET /api/access-control/roles/basic_ ``` Where `` is one of: `viewer`, `editor`, `admin`, or `grafana_admin`. For example, to get the Viewer role definition: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash curl --location 'https://.grafana.net/api/access-control/roles/basic_viewer' \ --header 'Authorization: Bearer ' ``` ### Using the browser You can also view the role definition directly in your browser by navigating to: ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```none https://.grafana.net/api/access-control/roles/basic_viewer ``` This works when logged in as an Admin user. For more information, refer to [Get a role](/docs/grafana-cloud/developer-resources/api-reference/http-api/access_control/#get-a-role). For a reference of basic and fixed role assignments, refer to [RBAC role definitions](/docs/grafana-cloud/account-management/authentication-and-permissions/access-control/rbac-fixed-basic-role-definitions/). ## Update role permissions If the default basic role permissions don’t meet your requirements you can change them. Basic roles are mutable. You can add or remove individual permissions on the `Viewer`, `Editor`, `Admin`, and `Grafana Admin` roles without creating a custom role. Each permission is a combination of an `action` and a `scope`. For example, you can remove access to a specific app plugin from all viewers by removing the relevant permissions from the `basic:viewer` role. Before you change basic role permissions, decide which roles to modify and how the change affects your users and teams. For planning guidance, refer to [Plan your RBAC rollout strategy](/docs/grafana-cloud/account-management/authentication-and-permissions/access-control/plan-rbac-rollout-strategy/). > Caution > > Changes that you make to a basic role apply to every [organization](/docs/grafana/next/administration/organization-management/) in the Grafana instance. For example, if you add the `fixed:users:writer` role’s permissions to the `Viewer` basic role, all viewers in every organization in the instance can create users. > > Basic role changes are scoped to a single Grafana instance. On Grafana Cloud, each stack is a separate instance, so you must apply the change to each stack individually. > Note > > If you only need to change access for specific users or teams rather than for every viewer, editor, or admin, leave the basic roles unchanged. Instead, assign the `No Basic Role` organization role and grant fixed or custom roles to those users or teams. For more information, refer to [Assign RBAC roles](/docs/grafana-cloud/account-management/authentication-and-permissions/access-control/assign-rbac-roles/). You can change basic roles’ permissions [via the configuration file](#update-basic-role-permissions-in-the-configuration-file) or [using the RBAC API](#update-basic-role-permissions-using-the-rbac-api). ### Update basic role permissions in the configuration file Before you begin, determine the permissions you want to add or remove from a basic role. For more information about the permissions associated with basic roles, refer to [RBAC role definitions](/docs/grafana-cloud/account-management/authentication-and-permissions/access-control/rbac-fixed-basic-role-definitions/#basic-role-assignments). > Note > > You cannot modify the `None` permissions. To change permissions for a basic role: 1. Open the YAML configuration file and locate the `roles` section. 2. Refer to the following table to add attributes and values. Expand table | Attribute | Description | |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| | `name` | The name of the basic role you want to update. You can specify a `uid` instead of a role name. The role `name` or the `uid` are required. | | `orgId` | Identifies the organization to which the role belongs. `global` can be used instead to specify it’s a global role. | | `version` | Identifies the version of the role, which prevents overwriting newer changes. | | `overrideRole` | If set to true, role will be updated regardless of its version in the database. There is no need to specify `version` if `overrideRole` is set to `true`. | | `from` | List of roles from which to copy permissions. | | `permissions > state` | The state of the permission. You can set it to `absent` to ensure it exclusion from the copy list. | 3. Reload the provisioning configuration file. For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations](/docs/grafana/next/developer-resources/api-reference/http-api/admin/#reload-provisioning-configurations). #### Example: Modify the Grafana Admin role The following example modifies the `Grafana Admin` basic role permissions. In the new configuration: - Permissions to list, grant, and revoke roles to teams are removed. - Permission to read and write Grafana folders is added. YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml # config file version apiVersion: 2 roles: - name: 'basic:grafana_admin' global: true version: 3 from: - name: 'basic:grafana_admin' global: true permissions: # Permissions to remove - action: 'teams.roles:read' scope: 'teams:*' state: 'absent' - action: 'teams.roles:remove' scope: 'permissions:type:delegate' state: 'absent' - action: 'teams.roles:add' scope: 'permissions:type:delegate' state: 'absent' # Permissions to add - action: 'folders:read' scope: 'folder:*' - action: 'folders:write' scope: 'folder:*' ``` > Note > > You can add multiple `fixed`, `basic` or `custom` roles to the `from` section. Their permissions will be copied and added to the basic role. Make sure to **increment** the role version for the changes to be accounted for. ### Update basic role permissions using the RBAC API Use the RBAC HTTP API when you want to change basic role permissions programmatically, for example from a script or a CI pipeline. The API uses two endpoints: - `GET /api/access-control/roles/{roleUID}` returns a basic role and all of its permissions. Refer to [Get a role](/docs/grafana-cloud/developer-resources/api-reference/http-api/access_control/#get-a-role). - `PUT /api/access-control/roles/{roleUID}` replaces the role’s permissions with the set that you send. Refer to [Update a role](/docs/grafana-cloud/developer-resources/api-reference/http-api/access_control/#update-a-role). Basic role UIDs follow the pattern `basic_`, where `` is `viewer`, `editor`, `admin`, or `grafana_admin`. Because `PUT` replaces the entire permission set, fetch the current role first, modify its permissions, increment its `version`, and then send the result back. Each request authenticates with a [service account token](/docs/grafana-cloud/account-management/authentication-and-permissions/service-accounts/) that has the `Role writer` role, or with basic authentication as a `Grafana Admin`. > Note > > Send `global: true` in the request body when you update a global basic role, and set `version` to a value higher than the current version. Grafana rejects updates that don’t increase the version. #### Example: Modify the Grafana Admin role using the API The following example makes the same change as the [configuration file example](#example-modify-the-grafana-admin-role) using the API instead. It removes the permissions to list, grant, and revoke roles to teams, and adds permissions to read and write Grafana folders. The script fetches the `basic:grafana_admin` role, removes and adds permissions with `jq`, increments the version, and updates the role: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash # Fetch the role, modify its permissions, and increment its version curl -H "Authorization: Bearer " \ -X GET '/api/access-control/roles/basic_grafana_admin' | \ jq 'del(.created) | del(.updated) | del(.permissions[].created) | del(.permissions[].updated) | .version += 1' | \ jq 'del(.permissions[] | select(.action == "teams.roles:read")) | del(.permissions[] | select(.action == "teams.roles:add")) | del(.permissions[] | select(.action == "teams.roles:remove"))' | \ jq '.permissions += [{"action": "folders:read", "scope": "folders:*"}, {"action": "folders:write", "scope": "folders:*"}]' > basic_grafana_admin.json # Update the role with the modified permissions curl -H "Authorization: Bearer " -H "Content-Type: application/json" \ -X PUT -d @basic_grafana_admin.json \ '/api/access-control/roles/basic_grafana_admin' ``` Replace the following placeholders: - *``* : A service account token with permission to read and write roles, for example `glsa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`. To use basic authentication instead, replace the `Authorization` header with `-u admin:`. - *``* : The base URL of your Grafana instance, for example `https://.grafana.net` on Grafana Cloud or `http://localhost:3000` for a local instance. The `jq` filters first strip the read-only `created` and `updated` timestamps and increment the role `version`, then remove the unwanted permissions, and finally append the new ones. The `PUT` request sends the resulting role definition back to Grafana. #### Example: Remove Grafana Assistant access from Viewers By default, viewers can access all app plugins that their organization role allows, including Grafana Assistant. To prevent viewers from accessing Grafana Assistant, remove the following permissions from the `basic:viewer` role: Expand table | Action | Scope | |--------------------------------------|------------------------------------| | `grafana-assistant-app.chats:access` | | | `plugins.app:access` | `plugins:id:grafana-assistant-app` | You can remove these permissions with the configuration file or with the API. Use the `role > from` list and `permission > state` option of your provisioning file to remove the permissions: YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml apiVersion: 2 roles: - name: 'basic:viewer' global: true version: 9 from: - name: 'basic:viewer' global: true permissions: - action: 'grafana-assistant-app.chats:access' state: 'absent' - action: 'plugins.app:access' scope: 'plugins:id:grafana-assistant-app' state: 'absent' ``` Alternatively, use the RBAC HTTP API. The following script fetches the `basic:viewer` role, removes the two Grafana Assistant permissions, increments the version, and updates the role: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash # Fetch the role, remove the Grafana Assistant permissions, and increment its version curl -H "Authorization: Bearer " \ -X GET '/api/access-control/roles/basic_viewer' | \ jq 'del(.created) | del(.updated) | del(.permissions[].created) | del(.permissions[].updated) | .version += 1' | \ jq 'del(.permissions[] | select(.action == "grafana-assistant-app.chats:access")) | del(.permissions[] | select(.action == "plugins.app:access" and .scope == "plugins:id:grafana-assistant-app"))' > basic_viewer.json # Update the role with the modified permissions curl -H "Authorization: Bearer " -H "Content-Type: application/json" \ -X PUT -d @basic_viewer.json \ '/api/access-control/roles/basic_viewer' ``` Replace the following placeholders: - *``* : A service account token with permission to read and write roles. - *``* : The base URL of your Grafana instance. To find the IDs of other app plugins, refer to [RBAC for app plugins](/docs/grafana-cloud/account-management/authentication-and-permissions/access-control/rbac-for-app-plugins/). That page also explains how to grant fine-grained app plugin access to specific users and teams without changing the basic roles. ## Reset basic roles to their default You have two options to reset the basic roles permissions to their default. ### Use the configuration option > **Note**: Available as of Grafana Enterprise 9.4. > Warning: If this option is left to true, permissions will be reset on every boot. Use the [`reset_basic_roles`](/docs/grafana-cloud/account-management/authentication-and-permissions/access-control/configure-rbac/#configure-rbac-in-grafana) option to reset basic roles permissions to their default on Grafana instance boot up. 1. Open you configuration file and update the rbac section as follow: Bash ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```bash [rbac] reset_basic_roles = true ``` ### Use the HTTP endpoint An alternative to the configuration option is to use the HTTP endpoint. 1. Open the YAML configuration file and locate the `roles` section. 2. Grant the `action: "roles:write", scope: "permissions:type:escalate` permission to `Grafana Admin`. Note that this permission has not been granted to any basic roles by default, because users could acquire more permissions than they previously had through the basic role permissions reset. YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy ```yaml apiVersion: 2 roles: - name: 'basic:grafana_admin' global: true version: 3 from: - name: 'basic:grafana_admin' global: true permissions: # Permission allowing to reset basic roles - action: 'roles:write' scope: 'permissions:type:escalate' ``` 3. As a `Grafana Admin`, call the API endpoint to reset the basic roles to their default. Refer to the [RBAC HTTP API](/docs/grafana-cloud/developer-resources/api-reference/http-api/access_control/#reset-basic-roles-to-their-default) for more details.