---
title: "Manage Grafana RBAC roles | Grafana 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/v12.4/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_<role>
```

Where `<role>` 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://<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 code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```none
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](/docs/grafana/v12.4/developers/http_api/access_control/#get-a-role).

For a reference of basic and fixed role assignments, refer to [RBAC role definitions](/docs/grafana/v12.4/administration/roles-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.

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/v12.4/administration/roles-and-permissions/access-control/rbac-fixed-basic-role-definitions/#basic-role-assignments).

> Note
> 
> You cannot modify the `No Basic Role` permissions.

**To change permissions from 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/v12.4/developers/http_api/admin/#reload-provisioning-configurations).

The following example modifies the `Grafana Admin` basic role permissions.

- 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.

You can also change basic roles’ permissions using the API. Refer to the [RBAC HTTP API](/docs/grafana/v12.4/developers/http_api/access_control/#update-a-role) for more details.

### Update basic role permissions using the RBAC API

Refer to the [RBAC HTTP API](/docs/grafana/v12.4/developers/http_api/access_control/#update-a-role) for more details.

## Reset basic roles to their default

This section describes how to reset the 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/v12.4/administration/roles-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/v12.4/developers/http_api/access_control/#reset-basic-roles-to-their-default) for more details.

## Delete a custom role using Grafana provisioning

Delete a custom role when you no longer need it. When you delete a custom role, the custom role is removed from users and teams to which it is assigned.

**Before you begin:**

- Identify the role or roles that you want to delete.
- Ensure that you have access to the YAML configuration file.

**To delete a custom 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 custom role you want to delete. 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.                                                                                     |
   | `state`   | The state of the role set to `absent` to trigger its removal.                                                                              |
   | `force`   | When set to `true`, the roles are removed even if there are existing assignments.                                                          |
3. Reload the provisioning configuration file.
   
   For more information about reloading the provisioning configuration at runtime, refer to [Reload provisioning configurations](/docs/grafana/v12.4/developers/http_api/admin/#reload-provisioning-configurations).

The following example deletes a custom role:

YAML ![Copy code to clipboard](/media/images/icons/icon-copy-small-2.svg) Copy

```yaml
# config file version
apiVersion: 2

roles:
  - name: 'custom:reports:editor'
    orgId: 1
    state: 'absent'
    force: true
```

You can also delete a custom role using the API. Refer to the [RBAC HTTP API](/docs/grafana/v12.4/developers/http_api/access_control/#delete-a-custom-role) for more details.