This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.

Documentation Grafana documentation Administration Roles and permissions Role-based access control (RBAC) Manage RBAC roles

Manage RBAC roles

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

GET /api/access-control/roles/basic_<role>

Where <role> is one of: viewer, editor, admin, or grafana_admin.

For example, to get the Viewer role definition:

Bash Copy

curl --location 'https://<your-stack-name>.grafana.net/api/access-control/roles/basic_viewer' \
  --header 'Authorization: Bearer <service-account-token>'

Using the browser

You can also view the role definition directly in your browser by navigating to:

Copy

https://<your-stack-name>.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.

For a reference of basic and fixed role assignments, refer to RBAC 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.

You can change basic roles’ permissions via the configuration file or 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.

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.

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

# 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:*'

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.
• PUT /api/access-control/roles/{roleUID} replaces the role’s permissions with the set that you send. Refer to Update a role.

Basic role UIDs follow the pattern basic_<role>, where <role> 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 that has the Role writer role, or with basic authentication as a Grafana Admin.

Example: Modify the Grafana Admin role using the API

The following example makes the same change as the configuration file example 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

# Fetch the role, modify its permissions, and increment its version
curl -H "Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>" \
  -X GET '<GRAFANA_URL>/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 <SERVICE_ACCOUNT_TOKEN>" -H "Content-Type: application/json" \
  -X PUT -d @basic_grafana_admin.json \
  '<GRAFANA_URL>/api/access-control/roles/basic_grafana_admin'

Replace the following placeholders:

• <SERVICE_ACCOUNT_TOKEN>: 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:<PASSWORD>.
• <GRAFANA_URL>: The base URL of your Grafana instance, for example https://<YOUR_STACK_NAME>.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:

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

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

# Fetch the role, remove the Grafana Assistant permissions, and increment its version
curl -H "Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>" \
  -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 == "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 <SERVICE_ACCOUNT_TOKEN>" -H "Content-Type: application/json" \
  -X PUT -d @basic_viewer.json \
  '<GRAFANA_URL>/api/access-control/roles/basic_viewer'

Replace the following placeholders:

• <SERVICE_ACCOUNT_TOKEN>: A service account token with permission to read and write roles.
• <GRAFANA_URL>: The base URL of your Grafana instance.

To find the IDs of other app plugins, refer to 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 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

[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

   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 for more details.