Fine-grained access control on Grafana Labs

Roles

Sat, 04 Apr 2026 12:26:57 +0000

Roles

A role represents set of permissions that allow you to perform specific actions on Grafana resources. Refer to Permissions to understand how permissions work.

There are two types of roles:

Fixed roles, which provide granular access for specific resources within Grafana and are managed by the Grafana itself.
Custom roles, which provide granular access based on the user specified set of permissions.

You can use Fine-grained access control API to list available roles and permissions.

Role scopes

A role can be either global or organization local. Global roles are not mapped to any specific organization and can be reused across multiple organizations, whereas organization local roles are only available for that specific organization.

Fixed roles

Fixed roles provide convenience and guarantee of consistent behaviour by combining relevant permissions together. Fixed roles are created and updated by Grafana during startup. There are few basic rules for fixed roles:

All fixed roles are global.
All fixed roles have a fixed: prefix.
You can’t change or delete a fixed role.

For more information, refer to Fine-grained access control references.

Custom roles

Custom roles allow you to manage access to your users the way you want, by mapping fine-grained permissions to it and creating built-in role assignments.

To create, update or delete a custom role, you can use the Fine-grained access control API or Grafana Provisioning.

Role name

A role’s name is intended as a human friendly identifier for the role, helping administrators understand the purpose of a role. The name cannot be longer than 190 characters, and we recommend using ASCII characters. Role names must be unique within an organization.

Roles with names prefixed by fixed: are fixed roles created by Grafana and cannot be created or modified by users.

Role display name

A role’s display name is human friendly text that is displayed in the UI. When you create a display name for a role, use up to 190 ASCII-based characters. For fixed roles, the display name is shown as specified. If the display name has not been set the display name replace any : (a colon) with (a space).

Display name

A role’s display name is a human-friendly identifier for the role, so that users more easily understand the purpose of a role. You can see the display name in the role picker in the UI.

Group

A role’s group organizes roles in the role picker in the UI.

Role version

The version of a role is a positive integer which defines the current version of the role. When updating a role, you can either omit the version field to increment the previous value by 1 or set a new version which must be strictly larger than the previous version for the update to succeed.

Permissions

You manage access to Grafana resources by mapping permissions to roles. You can create and assign roles without any permissions as placeholders.

Role UID

Each custom role has a UID defined which is a unique identifier associated with the role allowing you to change or delete the role. You can either generate UID yourself, or let Grafana generate one for you.

The same UID cannot be used for roles in different organizations within the same Grafana instance.

Create, update and delete roles

You can create, update and delete custom roles by using the Access Control HTTP API or by using Grafana Provisioning.

By default, Grafana Server Admin has a built-in role assignment which allows a user to create, update or delete custom roles. If a Grafana Server Admin wants to delegate that privilege to other users, they can create a custom role with relevant permissions and permissions:delegate scope will allow those users to manage roles themselves.

Note that you won’t be able to create, update or delete a custom role with permissions which you yourself do not have. For example, if the only permission you have is a users:create, you won’t be able to create a role with other permissions.

Assign roles

Custom roles and Fixed roles can be assigned to users, the existing Organization roles and to Grafana Server Admin role.

Visit Manage role assignments page for more details.

Scope of assignments

A role assignment can be either global or organization local. Global assignments are not mapped to any specific organization and will be applied to all organizations, whereas organization local assignments are only applied for that specific organization. You can only create organization local assignments for organization local roles.

Permissions

Sat, 04 Apr 2026 12:26:57 +0000

Permissions

A permission is an action and a scope. When creating a fine-grained access control, consider what specific action a user should be allowed to perform, and on what resources (its scope).

To grant permissions to a user, you create a built-in role assignment to map a role to a built-in role. A built-in role assignment modifies to one of the existing built-in roles in Grafana (Viewer, Editor, Admin). For more information, refer to Built-in role assignments.

To learn more about which permissions are used for which resources, refer to Resources with fine-grained permissions.

action: The specific action on a resource defines what a user is allowed to perform if they have permission with the relevant action assigned to it.
scope: The scope describes where an action can be performed, such as reading a specific user profile. In such case, a permission is associated with the scope users:<userId> to the relevant role.

Action definitions

The following list contains fine-grained access control actions.

Action	Applicable scope	Description
`roles:list`	`roles:*`	List available roles without permissions.
`roles:read`	`roles:` `roles:uid:`	Read a specific role with its permissions.
`roles:write`	`permissions:delegate`	Create or update a custom role.
`roles:delete`	`permissions:delegate`	Delete a custom role.
`roles.builtin:list`	`roles:*`	List built-in role assignments.
`roles.builtin:add`	`permissions:delegate`	Create a built-in role assignment.
`roles.builtin:remove`	`permissions:delegate`	Delete a built-in role assignment.
`reports.admin:create`	n/a	Create reports.
`reports.admin:write`	`reports:` `reports:id:`	Update reports.
`reports:delete`	`reports:` `reports:id:`	Delete reports.
`reports:read`	`reports:*`	List all available reports or get a specific report.
`reports:send`	`reports:*`	Send a report email.
`reports.settings:write`	n/a	Update report settings.
`reports.settings:read`	n/a	Read report settings.
`provisioning:reload`	`provisioners:*`	Reload provisioning files. To find the exact scope for specific provisioner, see Scope definitions.
`users:read`	`global:users:*`	Read or search user profiles.
`users:write`	`global:users:*` `global:users:id`	Update a user’s profile.
`users.teams:read`	`global:users:` `global:users:id:`	Read a user’s teams.
`users.authtoken:list`	`global:users:` `global:users:id:`	List authentication tokens that are assigned to a user.
`users.authtoken:update`	`global:users:` `global:users:id:`	Update authentication tokens that are assigned to a user.
`users.password:update`	`global:users:` `global:users:id:`	Update a user’s password.
`users:delete`	`global:users:` `global:users:id:`	Delete a user.
`users:create`	n/a	Create a user.
`users:enable`	`global:users:` `global:users:id:`	Enable a user.
`users:disable`	`global:users:` `global:users:id:`	Disable a user.
`users.permissions:update`	`global:users:` `global:users:id:`	Update a user’s organization-level permissions.
`users:logout`	`global:users:` `global:users:id:`	Sign out a user.
`users.quotas:list`	`global:users:` `global:users:id:`	List a user’s quotas.
`users.quotas:update`	`global:users:` `global:users:id:`	Update a user’s quotas.
`users.roles:list`	`users:*`	List roles assigned directly to a user.
`users.roles:add`	`permissions:delegate`	Assign a role to a user.
`users.roles:remove`	`permissions:delegate`	Unassign a role from a auser.
`users.permissions:list`	`users:*`	List permissions of a user.
`org.users:read`	`users:` `users:id:`	Get user profiles within an organization.
`org.users:add`	`users:*`	Add a user to an organization.
`org.users:remove`	`users:` `users:id:`	Remove a user from an organization.
`org.users.role:update`	`users:` `users:id:`	Update the organization role (`Viewer`, `Editor`, or `Admin`) of an organization.
`orgs:read`	`orgs:` `orgs:id:`	Read one or more organizations.
`orgs:write`	`orgs:` `orgs:id:`	Update one or more organizations.
`org:create`	n/a	Create an organization.
`orgs:delete`	`orgs:` `orgs:id:`	Delete one or more organizations.
`orgs.quotas:read`	`orgs:` `orgs:id:`	Read organization quotas.
`orgs.quotas:write`	`orgs:` `orgs:id:`	Update organization quotas.
`orgs.preferences:read`	`orgs:` `orgs:id:`	Read organization preferences.
`orgs.preferences:write`	`orgs:` `orgs:id:`	Update organization preferences.
`ldap.user:read`	n/a	Read users via LDAP.
`ldap.user:sync`	n/a	Sync users via LDAP.
`ldap.status:read`	n/a	Verify the availability of the LDAP server or servers.
`ldap.config:reload`	n/a	Reload the LDAP configuration.
`status:accesscontrol`	`services:accesscontrol`	Get access-control enabled status.
`settings:read`	`settings:` `settings:auth.saml:` `settings:auth.saml:enabled` (property level)	Read the Grafana configuration settings
`settings:write`	`settings:` `settings:auth.saml:` `settings:auth.saml:enabled` (property level)	Update any Grafana configuration settings that can be updated at runtime.
`server.stats:read`	n/a	Read Grafana instance statistics.
`datasources:explore`	n/a	Enable access to the Explore tab.
`datasources:read`	n/a `datasources:` `datasources:id:` `datasources:uid:` `datasources:name:`	List data sources.
`datasources:query`	n/a `datasources:` `datasources:id:`	Query data sources.
`datasources.id:read`	`datasources:` `datasources:name:`	Read data source IDs.
`datasources:create`	n/a	Create data sources.
`datasources:write`	`datasources:` `datasources:id:`	Update data sources.
`datasources:delete`	`datasources:id:` `datasources:uid:` `datasources:name:*`	Delete data sources.
`datasources.permissions:read`	`datasources:` `datasources:id:`	List data source permissions.
`datasources.permissions:write`	`datasources:` `datasources:id:`	Update data source permissions.
`licensing:read`	n/a	Read licensing information.
`licensing:update`	n/a	Update the license token.
`licensing:delete`	n/a	Delete the license token.
`licensing.reports:read`	n/a	Get custom permission reports.
`teams:create`	n/a	Create teams.
`teams:read`	`teams:` `teams:id:`	Read one or more teams and team preferences.
`teams:write`	`teams:` `teams:id:`	Update one or more teams and team preferences.
`teams:delete`	`teams:` `teams:id:`	Delete one or more teams.
`teams.permissions:read`	`teams:` `teams:id:`	Read members and External Group Synchronization setup for teams.
`teams.permissions:write`	`teams:` `teams:id:`	Add, remove and update members and manage External Group Synchronization setup for teams.

Scope definitions

The following list contains fine-grained access control scopes.

Scopes	Descriptions
`permissions:delegate`	The scope is only applicable for roles associated with the Access Control itself and indicates that you can delegate your permissions only, or a subset of it, by creating a new role or making an assignment.
`roles:` `roles:uid:`	Restrict an action to a set of roles. For example, `roles:*` matches any role and `roles:uid:randomuid` matches only the role whose UID is `randomuid`.
`reports:` `reports:id:`	Restrict an action to a set of reports. For example, `reports:*` matches any report and `reports:id:1` matches the report whose ID is `1`.
`services:accesscontrol`	Restrict an action to target only the fine-grained access control service. You can use this in conjunction with the `status:accesscontrol` actions.
`global:users:` `global:users:id:`	Restrict an action to a set of global users. For example, `global:users:*` matches any user and `global:users:id:1` matches the user whose ID is `1`.
`users:` `users:id:`	Restrict an action to a set of users from an organization. For example, `users:*` matches any user and `users:id:1` matches the user whose ID is `1`.
`orgs:` `orgs:id:`	Restrict an action to a set of organizations. For example, `orgs:*` matches any organization and `orgs:id:1` matches the organization whose ID is `1`.
`settings:*`	Restrict an action to a subset of settings. For example, `settings:` matches all settings, `settings:auth.saml:` matches all SAML settings, and `settings:auth.saml:enabled` matches the enable property on the SAML settings.
`provisioners:*`	Restrict an action to a set of provisioners. For example, `provisioners:*` matches any provisioner, and `provisioners:accesscontrol` matches the fine-grained access control provisioner.
`datasources:` `datasources:id:` `datasources:uid:` `datasources:name:`	Restrict an action to a set of data sources. For example, `datasources:*` matches any data source, and `datasources:name:postgres` matches the data source named `postgres`.

Manage role assignments

Sat, 04 Apr 2026 12:26:57 +0000

Manage role assignments

To grant or revoke access to your users, you can assign Roles to users, Organization roles and Grafana Server Admin role.

The following pages provide more information on how to manage role assignments:

Provisioning roles and assignments

Sat, 04 Apr 2026 12:26:57 +0000

Provisioning

You can create, change or remove Custom roles and create or remove built-in role assignments, by adding one or more YAML configuration files in the provisioning/access-control/ directory. Refer to Grafana provisioning to learn more about provisioning.

If you want to manage roles and built-in role assignments by API, refer to the Fine-grained access control HTTP API.

Configuration

The configuration files must be placed in provisioning/access-control/. Grafana performs provisioning during the startup. Refer to the Reload provisioning configurations to understand how you can reload configuration at runtime.

Manage custom roles

You can create, update, and delete custom roles, as well as create and remove built-in role assignments.

Create or update roles

To create or update custom roles, you can add a list of roles in the configuration.

Every role has a version number. For each role you update, you must remember to increment it, otherwise changes won’t be applied.

When you update a role, the existing role inside Grafana is altered to be exactly what is specified in the YAML file, including permissions.

Here is an example YAML file to create a local role with a set of permissions:

# config file version
apiVersion: 1

# Roles to insert into the database, or roles to update in the database
roles:
  - name: custom:users:editor
    description: 'This role allows users to list, create, or update other users within the organization.'
    version: 1
    orgId: 1
    permissions:
      - action: 'users:read'
        scope: 'users:*'
      - action: 'users:write'
        scope: 'users:*'
      - action: 'users:create'
        scope: 'users:*'

Here is an example YAML file to create a global role with a set of permissions, where the global:true option makes a role global:

# config file version
apiVersion: 1

# Roles to insert into the database, or roles to update in the database
roles:
  - name: custom:users:editor
    description: 'This role allows users to list, create, or update other users within the organization.'
    version: 1
    global: true
    permissions:
      - action: 'users:read'
        scope: 'users:*'
      - action: 'users:write'
        scope: 'users:*'
      - action: 'users:create'
        scope: 'users:*'

The orgId is lost when the role is set to global.

Delete roles

To delete a role, add a list of roles under the deleteRoles section in the configuration file.

Note: Any role in the deleteRoles section is deleted before any role in the roles section is saved.

Here is an example YAML file to delete a role:

# config file version
apiVersion: 1

# list of roles that should be deleted
deleteRoles:
  - name: custom:reports:editor
    orgId: 1
    force: true

Assign your custom role to specific built-in roles

To assign roles to built-in roles, add said built-in roles to the builtInRoles section of your roles. To remove a specific assignment, remove it from the list.

Note: Assignments are updated if the version of the role is greater or equal to the one stored internally. You don’t need to increment the version number of the role to update its assignments.

For example, the following role is assigned to an organization editor or an organization administrator:

# config file version
apiVersion: 1

# Roles to insert/update in the database
roles:
  - name: custom:users:editor
    description: 'This role allows users to list/create/update other users in the organization'
    version: 1
    orgId: 1
    permissions:
      - action: 'users:read'
        scope: 'users:*'
      - action: 'users:write'
        scope: 'users:*'
      - action: 'users:create'
        scope: 'users:*'
    builtInRoles:
      - name: 'Editor'
      - name: 'Admin'

Assign your custom role to specific teams

To assign roles to teams, add said teams to the teams section of your roles. To remove a specific assignment, remove it from the list.

Note: Assignments are updated if the version of the role is greater or equal to the one stored internally.
You don’t need to increment the version number of the role to update its assignments.
Assignments to built-in roles will be ignored. Use addDefaultAssignments and removeDefaultAssignments instead.

In order for provisioning to succeed, specified teams must already exist. Additionally, since teams are local to an organization, the organization has to be specified in the assignment.

For example, the following role is assigned to the user editors team and user admins team:

# config file version
apiVersion: 1

# Roles to insert/update in the database
roles:
  - name: custom:users:writer
    description: 'List/update other users in the organization'
    version: 1
    global: true
    permissions:
      - action: 'org.users:read'
        scope: 'users:*'
      - action: 'org.users:write'
        scope: 'users:*'
    teams:
      - name: 'user editors'
        orgId: 1
      - name: 'user admins'
        orgId: 1

Assign fixed roles to specific teams

To assign a fixed role to teams, add said teams to the teams section of the associated entry. To remove a specific assignment, remove it from the list.

Note: Since fixed roles are global, the Global attribute has to be specified. A fixed role will never be updated through provisioning.

In order for provisioning to succeed, specified teams must already exist. Additionally, since teams are local to an organization, the organization has to be specified in the assignment.

For example, the following fixed role is assigned to the user editors team and user admins team:

# config file version
apiVersion: 1

# Roles to insert/update in the database
roles:
  - name: fixed:users:writer
    global: true
    teams:
      - name: 'user editors'
        orgId: 1
      - name: 'user admins'
        orgId: 1

Manage default built-in role assignments

During startup, Grafana creates default built-in role assignments with fixed roles. You can remove and later restore those assignments with provisioning.

Remove default assignment

To remove default built-in role assignments, use the removeDefaultAssignments element in the configuration file. You need to provide the built-in role name and fixed role name.

Here is an example:

# config file version
apiVersion: 1

# list of default built-in role assignments that should be removed
removeDefaultAssignments:
  - builtInRole: 'Grafana Admin'
    fixedRole: 'fixed:permissions:admin'

Restore default assignment

To restore the default built-in role assignment, use the addDefaultAssignments element in the configuration file. You need to provide the built-in role name and the fixed-role name.

Here is an example:

# config file version
apiVersion: 1

# list of default built-in role assignments that should be added back
addDefaultAssignments:
  - builtInRole: 'Admin'
    fixedRole: 'fixed:reporting:admin:read'

Full example of a role configuration file

# config file version
apiVersion: 1

# list of default built-in role assignments that should be removed
removeDefaultAssignments:
  # <string>, must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
  - builtInRole: 'Grafana Admin'
    # <string>, must be one of the existing fixed roles
    fixedRole: 'fixed:permissions:admin'

# list of default built-in role assignments that should be added back
addDefaultAssignments:
  # <string>, must be one of the Organization roles (`Viewer`, `Editor`, `Admin`) or `Grafana Admin`
  - builtInRole: 'Admin'
    # <string>, must be one of the existing fixed roles
    fixedRole: 'fixed:reporting:admin:read'

# list of roles that should be deleted
deleteRoles:
  # <string> name of the role you want to create. Required if no uid is set
  - name: 'custom:reports:editor'
    # <string> uid of the role. Required if no name
    uid: 'customreportseditor1'
    # <int> org id. will default to Grafana's default if not specified
    orgId: 1
    # <bool> force deletion revoking all grants of the role
    force: true
  - name: 'custom:global:reports:reader'
    uid: 'customglobalreportsreader1'
    # <bool> overwrite org id and removes a global role
    global: true
    force: true

# list of roles to insert/update depending on what is available in the database
roles:
  # <string, required> name of the role you want to create. Required
  - name: 'custom:users:editor'
    # <string> uid of the role. Has to be unique for all orgs.
    uid: customuserseditor1
    # <string> description of the role, informative purpose only.
    description: 'Role for our custom user editors'
    # <int> version of the role, Grafana will update the role when increased
    version: 2
    # <int> org id. will default to Grafana's default if not specified
    orgId: 1
    # <list> list of the permissions granted by this role
    permissions:
      # <string, required> action allowed
      - action: 'users:read'
        #<string> scope it applies to
        scope: 'users:*'
      - action: 'users:write'
        scope: 'users:*'
      - action: 'users:create'
        scope: 'users:*'
    # <list> list of builtIn roles the role should be assigned to
    builtInRoles:
      # <string, required> name of the builtin role you want to assign the role to
      - name: 'Editor'
        # <int> org id. will default to the role org id
        orgId: 1
  - name: 'custom:global:users:reader'
    uid: 'customglobalusersreader1'
    description: 'Global Role for custom user readers'
    version: 1
    # <bool> overwrite org id and creates a global role
    global: true
    permissions:
      - action: 'users:read'
        scope: 'users:*'
    builtInRoles:
      - name: 'Viewer'
        orgId: 1
      - name: 'Editor'
        # <bool> overwrite org id and assign role globally
        global: true
  - name: fixed:users:writer
    global: true
    # <list> list of teams the role should be assigned to
    teams:
      - name: 'user editors'
        orgId: 1

Supported settings

The following sections detail the supported settings for roles and built-in role assignments.

Refer to Permissions for full list of valid permissions.
Check Custom roles to understand attributes for roles.
The default org ID is used if orgId is not specified in any of the configuration blocks.

Validation rules

A basic set of validation rules are applied to the input yaml files.

Roles

name must not be empty
name must not have fixed: prefix.

Permissions

name must not be empty

Built-in role assignments

name must be one of the Organization roles (Viewer, Editor, Admin) or Grafana Admin.
When orgId is not specified, it inherits the orgId from role. For global roles the default orgId is used.
orgId in the role and in the assignment must be the same for none global roles.

Role deletion

Either the role name or uid must be provided

Fine-grained access control usage scenarios

Sat, 04 Apr 2026 12:26:57 +0000

Fine-grained access control usage scenarios

This guide contains several examples and usage scenarios of using fine-grained roles and permissions for controlling access to Grafana resources.

Before you get started, make sure to enable fine-grained access control.

Check all built-in role assignments

You can use the Fine-grained access control HTTP API to see all available built-in role assignments. The response contains a mapping between one of the organization roles (Viewer, Editor, Admin) or Grafana Admin to the custom or fixed roles.

Example request:

curl --location --request GET '<grafana_url>/api/access-control/builtin-roles' --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ='

You must use the base64 username:password Basic Authorization here. Auth tokens are not applicable here.

Example response:

{
    "Admin": [
        ...
        {
            "version": 2,
            "uid": "qQui_LCMk",
            "name": "fixed:users:org:writer",
            "displayName": "Users Organization writer",
            "description": "Within a single organization, add a user, invite a user, read information about a user and their role, remove a user from that organization, or change the role of a user.",
            "global": true,
            "updated": "2021-05-17T20:49:18+02:00",
            "created": "2021-05-13T16:24:26+02:00"
        },
        {
            "version": 1,
            "uid": "Kz9m_YjGz",
            "name": "fixed:reports:writer",
            "displayName": "Report writer",
            "description": "Create, read, update, or delete all reports and shared report settings.",
            "global": true,
            "updated": "2021-05-13T16:24:26+02:00",
            "created": "2021-05-13T16:24:26+02:00"
        }
        ...
    ],
    "Grafana Admin": [
        ...
        {
            "version": 2,
            "uid": "qQui_LCMk",
            "name": "fixed:users:writer",
            "displayName": "User writer",
            "description": "Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users.",
            "global": true,
            "updated": "2021-05-17T20:49:18+02:00",
            "created": "2021-05-13T16:24:26+02:00"
        },
        {
            "version": 2,
            "uid": "ajum_YjGk",
            "name": "fixed:users:reader",
            "displayName": "User reader",
            "description": "Allows every read action for user organizations and in addition allows to administer user organizations.",
            "global": true,
            "updated": "2021-05-17T20:49:17+02:00",
            "created": "2021-05-13T16:24:26+02:00"
        },
        ...
    ]
}

To see what permissions each of the assigned roles have, you can a Get a role by using an HTTP API.

Example request:

curl --location --request GET '<grafana_url>/api/access-control/roles/qQui_LCMk' --header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ='

Example response:

{
    "version": 2,
    "uid": "qQui_LCMk",
    "name": "fixed:users:writer",
    "displayName": "User writer",
    "description": "Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users.",
    "global": true,
    "permissions": [
        {
            "action": "org.users:add",
            "scope": "users:*",
            "updated": "2021-05-17T20:49:18+02:00",
            "created": "2021-05-17T20:49:18+02:00"
        },
        {
            "action": "org.users:read",
            "scope": "users:*",
            "updated": "2021-05-17T20:49:18+02:00",
            "created": "2021-05-17T20:49:18+02:00"
        },
        {
            "action": "org.users:remove",
            "scope": "users:*",
            "updated": "2021-05-17T20:49:18+02:00",
            "created": "2021-05-17T20:49:18+02:00"
        },
        {
            "action": "org.users.role:update",
            "scope": "users:*",
            "updated": "2021-05-17T20:49:18+02:00",
            "created": "2021-05-17T20:49:18+02:00"
        }
    ],
    "updated": "2021-05-17T20:49:18+02:00",
    "created": "2021-05-13T16:24:26+02:00"
}

Manage roles granted directly to users

To learn about granting roles to users, refer to Manage user role assignments page.

Create your first custom role

You can create your custom role by either using an HTTP API or by using Grafana provisioning. You can take a look at actions and scopes to decide what permissions would you like to map to your role.

Example HTTP request:

curl --location --request POST '<grafana_url>/api/access-control/roles/' \
--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
--header 'Content-Type: application/json' \
--data-raw '{
    "version": 1,
    "uid": "jZrmlLCkGksdka",
    "name": "custom:users:admin",
    "displayName": "custom users admin",
    "description": "My custom role which gives users permissions to create users",
    "global": true,
    "permissions": [
        {
            "action": "users:create"
        }
    ]
}'

Example response:

{
    "version": 1,
    "uid": "jZrmlLCkGksdka",
    "name": "custom:users:admin",
    "displayName": "custom users admin",
    "description": "My custom role which gives users permissions to create users",
    "global": true,
    "permissions": [
        {
            "action": "users:create"
            "updated": "2021-05-17T22:07:31.569936+02:00",
            "created": "2021-05-17T22:07:31.569935+02:00"
        }
    ],
    "updated": "2021-05-17T22:07:31.564403+02:00",
    "created": "2021-05-17T22:07:31.564403+02:00"
}

Once the custom role is created, you can create a built-in role assignment by using an HTTP API. If you created your role using Grafana provisioning, you can also create the assignment with it.

Example HTTP request:

curl --location --request POST '<grafana_url>/api/access-control/builtin-roles' \
--header 'Authorization: Basic YWRtaW46cGFzc3dvcmQ=' \
--header 'Content-Type: application/json' \
--data-raw '{
    "roleUid": "jZrmlLCkGksdka",
    "builtinRole": "Viewer",
    "global": true
}'

Example response:

{
    "message": "Built-in role grant added"
}

Allow Viewers to create reports

In order to create reports, you need to have reports.admin:write permission. By default, a Grafana Admin or organization Admin can create reports as there is a built-in role assignment which comes with reports.admin:write permission.

If you want your users who have the Viewer organization role to create reports, you have two options:

Create a built-in role assignment and map the fixed:reporting:admin:edit fixed role to the Viewer built-in role. Note that the fixed:reporting:admin:edit fixed role allows doing more than creating reports. Refer to fixed roles for full list of permission assignments.
Create a custom role with reports.admin:write permission, and create a built-in role assignment for Viewer organization role.

Prevent Grafana Admin from creating and inviting users

In order to create users, you need to have users:create permission. By default, a user with the Grafana Admin role can create users as there is a built-in role assignment which comes with users:create permission.

If you want to prevent Grafana Admin from creating users, you can do the following:

Check all built-in role assignments to see what built-in role assignments are available.
From built-in role assignments, find the role which gives users:create permission. Refer to fixed roles for full list of permission assignments.
Remove the built-in role assignment by using an Fine-grained access control HTTP API or by using Grafana provisioning.

Allow Editors to create new custom roles

By default, the Grafana Server Admin is the only user who can create and manage custom roles. If you want your users to do the same, you have two options:

Create a built-in role assignment and map fixed:permissions:admin:edit and fixed:permissions:admin:read fixed roles to the Editor built-in role.
Create a custom role with roles.builtin:add and roles:write permissions, then create a built-in role assignment for Editor organization role.

Note that any user with the ability to modify roles can only create, update or delete roles with permissions they themselves have been granted. For example, a user with the Editor role would be able to create and manage roles only with the permissions they have, or with a subset of them.

Fine-grained access control references

Sat, 04 Apr 2026 12:26:57 +0000

Fine-grained access control references

The reference information that follows complements conceptual information about Roles.

Fine-grained access fixed roles

Fixed roles	Permissions	Descriptions
`fixed:roles:reader`	`roles:read` `roles:list` `users.roles:list` `users.permissions:list` `roles.builtin:list`	Read all access control roles, roles and permissions assigned to users and built-in role assignments.
`fixed:roles:writer`	All permissions from `fixed:roles:reader` and `roles:write` `roles:delete` `users.roles:add` `users.roles:remove` `roles.builtin:add` `roles.builtin:remove`	Create, read, update, or delete all roles, assign or unassign roles to users and built-in role assignments.
`fixed:reports:reader`	`reports:read` `reports:send` `reports.settings:read`	Read all reports and shared report settings.
`fixed:reports:writer`	All permissions from `fixed:reports:reader` and `reports.admin:write` `reports:delete` `reports.settings:write`	Create, read, update, or delete all reports and shared report settings.
`fixed:users:reader`	`users:read` `users.quotas:list` `users.authtoken:list` `users.teams:read`	Read all users and their information, such as team memberships, authentication tokens, and quotas.
`fixed:users:writer`	All permissions from `fixed:users:reader` and `users:write` `users:create` `users:delete` `users:enable` `users:disable` `users.password:update` `users.permissions:update` `users:logout` `users.authtoken:update` `users.quotas:update`	Read and update all attributes and settings for all users in Grafana: update user information, read user information, create or enable or disable a user, make a user a Grafana administrator, sign out a user, update a user’s authentication token, or update quotas for all users.
`fixed:org.users:reader`	`org.users:read`	Read users within a single organization.
`fixed:org.users:writer`	All permissions from `fixed:org.users:reader` and `org.users:add` `org.users:remove` `org.users.role:update`	Within a single organization, add a user, invite a user, read information about a user and their role, remove a user from that organization, or change the role of a user.
`fixed:ldap:reader`	`ldap.user:read` `ldap.status:read`	Read the LDAP configuration and LDAP status information.
`fixed:ldap:writer`	All permissions from `fixed:ldap:reader` and `ldap.user:sync` `ldap.config:reload`	Read and update the LDAP configuration, and read LDAP status information.
`fixed:stats:reader`	`server.stats:read`	Read Grafana instance statistics.
`fixed:settings:reader`	`settings:read`	Read Grafana instance settings.
`fixed:settings:writer`	All permissions from `fixed:settings:reader` and `settings:write`	Read and update Grafana instance settings.
`fixed:datasources:explorer`	`datasources:explore`	Enable the Explore feature. Data source permissions still apply, you can only query data sources for which you have query permissions.
`fixed:datasources:reader`	`datasources:read` `datasources:query`	Read and query data sources.
`fixed:datasources:writer`	All permissions from `fixed:datasources:reader` and `datasources:create` `datasources:write` `datasources:delete`	Read, query, create, delete, or update a data source.
`fixed:datasources:id:reader`	`datasources.id:read`	Read the ID of a data source based on its name.
`fixed:datasources.permissions:reader`	`datasources.permissions:read`	Read data source permissions.
`fixed:datasources.permissions:writer`	All permissions from `fixed:datasources.permissions:reader` and `datasources.permissions:write`	Create, read, or delete permissions of a data source.
`fixed:licensing:reader`	`licensing:read` `licensing.reports:read`	Read licensing information and licensing reports.
`fixed:licensing:writer`	All permissions from `fixed:licensing:viewer` and `licensing:update` `licensing:delete`	Read licensing information and licensing reports, update and delete the license token.
`fixed:provisioning:writer`	`provisioning:reload`	Reload provisioning.
`fixed:organization:reader`	`orgs:read` `orgs.quotas:read`	Read an organization and its quotas.
`fixed:organization:writer`	All permissions from `fixed:organization:reader` and `orgs:write` `orgs.preferences:read` `orgs.preferences:write`	Read an organization, its quotas, or its preferences. Update organization properties, or its preferences.
`fixed:organization:maintainer`	All permissions from `fixed:organization:reader` and `orgs:write` `orgs:create` `orgs:delete` `orgs.quotas:write`	Create, read, write, or delete an organization. Read or write its quotas. This role needs to be assigned globally.
`fixed:teams:creator` `	`teams:create` `org.users:read`	Create a team and list organization users (required to manage the created team).
`fixed:teams:writer`	`teams:create` `teams:delete` `teams:read` `teams:write` `teams.permissions:read` `teams.permissions:write`	Create, read, update and delete teams and manage team memberships.

Default built-in role assignments

Built-in role	Associated role	Description
Grafana Admin	`fixed:roles:reader` `fixed:roles:writer` `fixed:users:reader` `fixed:users:writer` `fixed:org.users:reader` `fixed:org.users:writer` `fixed:ldap:reader` `fixed:ldap:writer` `fixed:stats:reader` `fixed:settings:reader` `fixed:settings:writer` `fixed:provisioning:writer` `fixed:organization:reader` `fixed:organization:maintainer` `fixed:licensing:reader` `fixed:licensing:writer`	Default Grafana server administrator assignments.
Admin	`fixed:reports:reader` `fixed:reports:writer` `fixed:datasources:reader` `fixed:datasources:writer` `fixed:organization:writer` `fixed:datasources.permissions:reader` `fixed:datasources.permissions:writer` `fixed:teams:writer`	Default Grafana organization administrator assignments.
Editor	`fixed:datasources:explorer` and `fixed:teams:creator` if the `editors_can_admin` configuration flag is enabled	Default Editor assignments.
Viewer	`fixed:datasources:id:reader` `fixed:organization:reader`	Default Viewer assignments.