Using Role-Based Access Control

1. Understanding RBAC

Concept	Description	Notes
Role	A collection of permissions that define what actions a user or service account can perform.	Roles can be assigned to users, teams, or service accounts.
Permission	A specific action or set of actions that a role allows.	Permissions are defined at the organization, folder, or dashboard level.
User	An individual who accesses Grafana with a specific role.	Users can be assigned multiple roles, which are additive.
Team	A group of users that can be assigned roles collectively.	Teams simplify role management for groups of users.
Service Account	An account used for automation or integration with external systems.	Service accounts can be assigned roles just like users.

Example: Assigning a Role to a User

// Example of assigning a role to a user in Grafana
{
  "user": {
    "login": "john.doe@example.com",
    "role": "Editor"
  }
}

Note: Grafana supports both built-in roles (Viewer, Editor, Admin) and custom roles defined by the organization.

Warning: Assigning the Admin role to a user grants full access to all resources and settings in Grafana.

2. Creating Custom Roles

Property	Description	Example
name	Name of the custom role	`Custom Admin`
description	Optional description of the role	`Admin with limited permissions`
permissions	List of permissions assigned to the role	`["datasources:read", "dashboards:write"]`

Example: Creating a Custom Role via API

{
  "name": "Custom Admin",
  "description": "Admin with limited permissions",
  "permissions": [
    "datasources:read",
    "dashboards:write"
  ]
}

Note: Custom roles can be assigned to users or teams in Grafana's RBAC system.

3. Assigning Roles to Users

Role	Description	Permissions	Assignment Method
Admin	Full access to all Grafana features and settings	All permissions including user management, data source configuration, and dashboard creation	UI: User Management → Edit User → Assign Role
Editor	Can create, edit, and delete dashboards; view and edit data sources	Dashboard creation/editing, data source access, folder permissions	UI: User Management → Edit User → Assign Role
Viewer	Can view dashboards and data sources but cannot make changes	Read-only access to dashboards and data sources	UI: User Management → Edit User → Assign Role
Grafana Admin	Full administrative control over Grafana instance	Access to all features, including user and organization management	UI: User Management → Edit User → Assign Role

Example: Assigning Admin Role via API

curl -X PUT "http://localhost:3000/api/users/1/roles" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "Admin"}'

Note: Role assignments can also be managed through the Grafana UI under Configuration > Users.

Warning: Admin role grants full access to Grafana and should be assigned carefully.

4. Assigning Roles to Teams

Team	Role	Notes
Admin Team	`Admin`	Full access to all Grafana features and data
Viewer Team	`Viewer`	Read-only access to dashboards and data
Editor Team	`Editor`	Can create and edit dashboards, but not manage users or settings

Example: Assigning Role via API

curl -X PUT "http://localhost:3000/api/teams/123/permissions" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "Editor"}'

Note: Team roles can be managed through the Grafana UI or API. Roles are inherited by all members of a team.

5. Configuring Role Permissions

Permission	Resource	Actions	Description
dashboards:read	`dashboard`	`GET /api/dashboards/*`	Allows reading dashboard data and metadata
dashboards:write	`dashboard`	`POST /api/dashboards/`, `PUT /api/dashboards/`	Allows creating and modifying dashboards
datasources:read	`datasource`	`GET /api/datasources/*`	Allows reading data source configurations
datasources:write	`datasource`	`POST /api/datasources/`, `PUT /api/datasources/`	Allows creating and modifying data sources
users:read	`user`	`GET /api/users/*`	Allows reading user information and settings
users:write	`user`	`POST /api/users/`, `PUT /api/users/`	Allows creating and modifying users

Example: Assigning Permissions to a Role

{
  "name": "Editor",
  "permissions": [
    {
      "action": "dashboards:read",
      "scope": "dashboard"
    },
    {
      "action": "dashboards:write",
      "scope": "dashboard"
    },
    {
      "action": "datasources:read",
      "scope": "datasource"
    }
  ]
}

Note: Permissions can be assigned at the organization, folder, or dashboard level depending on the scope.

6. Using Built-in Roles

Role	Description	Permissions	Assigned to
Admin	Full access to all features and settings	All permissions	System administrators
Editor	Can create and edit dashboards, data sources, and folders	Read and write access to dashboards, datasources, folders	Content creators
Viewer	Can view dashboards and data sources but not edit them	Read access to dashboards, datasources, folders	Read-only users
Grafana Admin	Full access to Grafana instance and all features	All permissions including user management, settings, plugins	Super administrators

Example: Assigning a built-in role to a user

curl -X PUT "http://localhost:3000/api/access-control/users/1/roles" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "Editor"}'

Note: Built-in roles cannot be modified or deleted. To customize permissions, create a custom role.

7. Setting Folder Permissions

Permission	Level	Description
Folder.View	Read	Allows viewing folder contents and metadata
Folder.Edit	Write	Allows editing folder properties and content
Folder.Admin	Admin	Allows full administrative control over folder

Example: Assigning Folder Permissions via API

curl --request POST \
  --url 'http://localhost:3000/api/folders/my-folder/permissions' \
  --header 'Authorization: Bearer <your_token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{\n  "items": [\n    {\n      "role": "Editor",\n      "permission": "Edit"\n    }\n  ]\n}'

Note: Folder permissions can be inherited from organization or team settings, but can also be overridden for specific folders.

8. Setting Data Source Permissions

Permission	Scope	Description
datasource:read	Data source	Allows reading data from the specified data source
datasource:write	Data source	Allows writing data to the specified data source
datasource:delete	Data source	Allows deleting the specified data source
datasource:edit	Data source	Allows editing configuration of the data source

Example: Assigning Data Source Permissions via API

curl -X POST "http://grafana.example.com/api/access-control/datasource/1/permissions" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d &#x27;{
    "permissions": [
      {
        "action": "datasource:read",
        "scope": "datasource:uid:abc123"
      }
    ]
  }&#x27;

Note: Permissions are scoped to specific data sources using their UID. Ensure the UID matches exactly to avoid permission errors.

9. Using Role Inheritance

In Grafana, role inheritance allows you to define a hierarchy of roles where a higher-level role can inherit permissions from lower-level roles. This simplifies the management of complex permission structures by reducing duplication and ensuring consistency across roles.

Property	Description	Values
role.name	Name of the role to be inherited	`Editor`, `Viewer`, `Admin`
role.parent	Parent role from which permissions are inherited	`Editor`, `Viewer`
role.permissions	Additional permissions specific to this role	List of permission strings

Example: Defining a Role with Inheritance

{
  "name": "TeamEditor",
  "parent": "Editor",
  "permissions": [
    "dashboards:write",
    "datasources:read"
  ]
}

Note: When a role inherits from another, it gains all the permissions of the parent role and can add or override specific permissions as needed.

10. Auditing Role Assignments

Field	Description	Example
user	User identifier or email	`john.doe@example.com`
role	Assigned role name	`Editor`
timestamp	Time of assignment	`2026-01-15T10:30:00Z`
source	How the role was assigned (API, UI, etc.)	`UI`

Example: Querying Role Assignment Logs

SELECT user, role, timestamp, source
FROM audit_log
WHERE event_type = 'role_assignment'
ORDER BY timestamp DESC
LIMIT 10;

Note: Audit logs are stored for 90 days by default in Grafana.