Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
RBAC API
Role-based access control API is only available in Grafana Enterprise. Read more about Grafana Enterprise.
The API can be used to create, update, delete, get, and list roles.
To check which basic or fixed roles have the required permissions, refer to RBAC role definitions.
Get status
GET /api/access-control/status
Returns an indicator to check if role-based access control is enabled or not.
Required permissions
Example request
GET /api/access-control/status
Accept: application/json
Content-Type: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"enabled": true
}
Status codes
Create and manage custom roles
Get all roles
GET /api/access-control/roles
Gets all existing roles. The response contains all global and organization local roles, for the organization which user is signed in.
Query Parameters:
includeHidden
: Optional. Set totrue
to include roles that arehidden
.
Required permissions
Example request
GET /api/access-control/roles
Accept: application/json
Content-Type: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"version": 3,
"uid": "XvHQJq57z",
"name": "fixed:reports:reader",
"displayName": "Report reader",
"description": "Read all reports and shared report settings.",
"group": "Reports",
"updated": "2021-11-19T10:48:00+01:00",
"created": "2021-11-19T10:48:00+01:00",
"global": false
},
{
"version": 5,
"uid": "vi9mlLjGz",
"name": "fixed:datasources.permissions:writer",
"description: "Create, read or delete data source permissions.",
"global": true,
"updated": "2021-05-13T22:41:49+02:00",
"created": "2021-05-13T16:24:26+02:00"
}
]
Status codes
Get a role
GET /api/access-control/roles/:uid
Get a role for the given UID.
Required permissions
Example request
GET /api/access-control/roles/PYnDO3rMk
Accept: application/json
Content-Type: application/json
Example response
Status codes
Create a new custom role
POST /api/access-control/roles
Creates a new custom role and maps given permissions to that role. Note that roles with the same prefix as Fixed roles can’t be created.
Required permissions
permissions:type:delegate
scope ensures that users can only create custom roles with the same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won’t be able to create a custom role which allows to do that. This is done to prevent escalation of privileges.
Example request
POST /api/access-control/roles
Accept: application/json
Content-Type: application/json
{
"version": 1,
"uid": "jZrmlLCGka",
"name": "custom:delete:roles",
"displayName": "custom delete roles",
"description": "My custom role which gives users permissions to delete roles",
"group":"My Group",
"displayName": "My Custom Role",
"global": false,
"permissions": [
{
"action": "roles:delete",
"scope": "permissions:type:delegate"
}
]
}
JSON body schema
Permission
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"version": 2,
"uid": "jZrmlLCGka",
"name": "custom:delete:create:roles",
"displayName": "custom delete create roles",
"description": "My custom role which gives users permissions to delete and create roles",
"group":"My Group",
"displayName": "My Custom Role",
"global": false,
"permissions": [
{
"action": "roles:delete",
"scope": "permissions:type:delegate",
"updated": "2021-05-13T23:19:46+02:00",
"created": "2021-05-13T23:19:46+02:00"
}
],
"updated": "2021-05-13T23:20:51.416518+02:00",
"created": "2021-05-13T23:19:46+02:00"
}
Status codes
Update a role
PUT /api/access-control/roles/:uid
Update the role with the given UID, and its permissions. The operation is idempotent and all permissions of the role will be replaced based on the request content. You need to increment the version of the role with each update, otherwise the request will fail.
You can update custom
roles and basic
roles permissions. However fixed
roles cannot be updated.
Required permissions
permissions:type:delegate
scope ensures that users can only update custom roles with the same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won’t be able to update a custom role which allows to do that. This is done to prevent escalation of privileges.
Example request
PUT /api/access-control/roles/jZrmlLCGka
Accept: application/json
Content-Type: application/json
{
"version": 3,
"name": "custom:delete:write:roles",
"displayName": "custom delete write roles",
"description": "My custom role which gives users permissions to delete and write roles",
"group":"My Group",
"displayName": "My Custom Role",
"global": false,
"permissions": [
{
"action": "roles:delete",
"scope": "permissions:type:delegate"
},
{
"action": "roles:write",
"scope": "permissions:type:delegate"
}
]
}
JSON body schema
Permission
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"version":3,
"uid":"jZrmlLCGka",
"name":"custom:delete:write:roles",
"displayName":"custom delete write roles",
"description":"My custom role which gives users permissions to delete and write roles",
"group":"My Group",
"displayName": "My Custom Role",
"permissions":[
{
"action":"roles:delete",
"scope":"permissions:type:delegate",
"updated":"2021-08-06T18:27:40+02:00",
"created":"2021-08-06T18:27:40+02:00"
},
{
"action":"roles:write",
"scope":"permissions:type:delegate",
"updated":"2021-08-06T18:27:41+02:00",
"created":"2021-08-06T18:27:41+02:00"
}
],
"updated":"2021-08-06T18:27:41+02:00",
"created":"2021-08-06T18:27:40+02:00",
"global":false
}
Status codes
Delete a custom role
DELETE /api/access-control/roles/:uid?force=false
Delete a role with the given UID, and it’s permissions. If the role is assigned, the deletion operation will fail, unless the force
query param is set to true
, and in that case all assignments will also be deleted.
Required permissions
permissions:type:delegate
scope ensures that users can only delete a custom role with the same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won’t be able to delete a custom role which allows to do that.
Example request
DELETE /api/access-control/roles/jZrmlLCGka?force=true&global=false
Accept: application/json
Query parameters
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Role deleted"
}
Status codes
Create and remove user role assignments
List roles assigned to a user
GET /api/access-control/users/:userId/roles
Lists the roles that have been directly assigned to a given user. The list does not include basic roles (Viewer, Editor, Admin or Grafana Admin), and it does not include roles that have been inherited from a team.
Query Parameters:
includeHidden
: Optional. Set totrue
to include roles that arehidden
.
Required permissions
Example request
GET /api/access-control/users/1/roles
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"version": 4,
"uid": "6dNwJq57z",
"name": "fixed:reports:writer",
"displayName": "Report writer",
"description": "Create, read, update, or delete all reports and shared report settings.",
"group": "Reports",
"updated": "2021-11-19T10:48:00+01:00",
"created": "2021-11-19T10:48:00+01:00",
"global": false
}
]
Status codes
List your permissions
GET /api/access-control/users/permissions
Lists the permissions granted to the signed in user.
Required permissions
No permission is required.
Query parameters
Example request
GET /api/access-control/user/permissions
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"dashboards:read": ["dashboards:uid:70KrY6IVz"],
"dashboards:write": ["dashboards:uid:70KrY6IVz"],
"datasources.id:read": ["datasources:*"],
"datasources:read": ["datasources:*"],
"datasources:explore": [""],
"datasources:query": ["datasources:uid:grafana"],
"datasources:read": ["datasources:uid:grafana"],
"orgs:read": [""]
}
Status codes
List permissions assigned to a user
GET /api/access-control/users/:userId/permissions
Lists the permissions granted to a given user.
Required permissions
Example request
GET /api/access-control/users/1/permissions
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"action": "ldap.status:read",
"scope": ""
},
{
"action": "ldap.user:read",
"scope": ""
}
]
Status codes
Add a user role assignment
POST /api/access-control/users/:userId/roles
Assign a role to a specific user.
For bulk updates consider Set user role assignments.
Required permissions
permissions:type:delegate
scope ensures that users can only assign roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won’t be able to assign a role which will allow to do that. This is done to prevent escalation of privileges.
Example request
POST /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json
{
"global": false,
"roleUid": "XvHQJq57z"
}
JSON body schema
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Role added to the user."
}
Status codes
Remove a user role assignment
DELETE /api/access-control/users/:userId/roles/:roleUID
Revoke a role from a user.
For bulk updates consider Set user role assignments.
Required permissions
permissions:type:delegate
scope ensures that users can only unassign roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won’t be able to unassign a role which will allow to do that. This is done to prevent escalation of privileges.
Query parameters
Example request
DELETE /api/access-control/users/1/roles/AFUXBHKnk
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Role removed from user."
}
Status codes
Set user role assignments
PUT /api/access-control/users/:userId/roles
Update the user’s role assignments to match the provided set of UIDs. This will remove any assigned roles that aren’t in the request and add roles that are in the set but are not already assigned to the user.
If you want to add or remove a single role, consider using Add a user role assignment or Remove a user role assignment instead.
Required permissions
permissions:type:delegate
scope ensures that users can only assign or unassign roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won’t be able to assign or unassign a role which will allow to do that. This is done to prevent escalation of privileges.
Example request
PUT /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json
{
"global": false,
"roleUids": [
"ZiHQJq5nk",
"GzNQ1357k"
]
}
JSON body schema
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "User roles have been updated."
}
Status codes
Create and remove service account role assignments
List roles assigned to a service account
GET /api/access-control/users/:serviceAccountId/roles
Lists the roles that have been directly assigned to a given service account. The list does not include basic roles (Viewer, Editor, Admin or Grafana Admin).
Query Parameters:
includeHidden
: Optional. Set totrue
to include roles that arehidden
.
Required permissions
Example request
GET /api/access-control/users/1/roles
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"version": 4,
"uid": "6dNwJq57z",
"name": "fixed:reports:writer",
"displayName": "Report writer",
"description": "Create, read, update, or delete all reports and shared report settings.",
"group": "Reports",
"updated": "2021-11-19T10:48:00+01:00",
"created": "2021-11-19T10:48:00+01:00",
"global": false
}
]
Status codes
List permissions assigned to a service account
GET /api/access-control/users/:serviceAccountId/permissions
Lists the permissions that a given service account has.
Required permissions
Example request
GET /api/access-control/users/1/permissions
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"action": "ldap.status:read",
"scope": ""
},
{
"action": "ldap.user:read",
"scope": ""
}
]
Status codes
Add a service account role assignment
POST /api/access-control/users/:serviceAccountId/roles
Assign a role to a specific service account.
For bulk updates consider Set service account role assignments.
Required permissions
permissions:type:delegate
scope ensures that users can only assign roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won’t be able to assign a role which will allow to do that. This is done to prevent escalation of privileges.
Example request
POST /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json
{
"global": false,
"roleUid": "XvHQJq57z"
}
JSON body schema
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Role added to the user."
}
Status codes
Remove a service account role assignment
DELETE /api/access-control/users/:serviceAccountId/roles/:roleUID
Revoke a role from a service account.
For bulk updates consider Set service account role assignments.
Required permissions
permissions:type:delegate
scope ensures that users can only unassign roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won’t be able to unassign a role which will allow to do that. This is done to prevent escalation of privileges.
Query parameters
Example request
DELETE /api/access-control/users/1/roles/AFUXBHKnk
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Role removed from user."
}
Status codes
Set service account role assignments
PUT /api/access-control/users/:serviceAccountId/roles
Update the service accounts’s role assignments to match the provided set of UIDs. This will remove any assigned roles that aren’t in the request and add roles that are in the set but are not already assigned to the service account.
If you want to add or remove a single role, consider using Add a service account role assignment or Remove a service account role assignment instead.
Required permissions
permissions:type:delegate
scope ensures that users can only assign or unassign roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won’t be able to assign or unassign a role which will allow to do that. This is done to prevent escalation of privileges.
Example request
PUT /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json
{
"global": false,
"roleUids": [
"ZiHQJq5nk",
"GzNQ1357k"
]
}
JSON body schema
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "User roles have been updated."
}
Status codes
Create and remove team role assignments
List roles assigned to a team
GET /api/access-control/teams/:teamId/roles
Lists the roles that have been directly assigned to a given team.
Query Parameters:
includeHidden
: Optional. Set totrue
to include roles that arehidden
.
Required permissions
Example request
GET /api/access-control/teams/1/roles
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"version": 4,
"uid": "j08ZBi-nk",
"name": "fixed:licensing:reader",
"displayName": "Licensing reader",
"description": "Read licensing information and licensing reports.",
"group": "Licenses",
"updated": "2022-02-03T14:19:50+01:00",
"created": "0001-01-01T00:00:00Z",
"global": false
}
]
Status codes
Add a team role assignment
POST /api/access-control/teams/:teamId/roles
Assign a role to a specific team.
For bulk updates consider Set team role assignments.
Required permissions
permissions:type:delegate
scope ensures that users can only assign roles which have same, or a subset of permissions which the user has.
For example, if a user does not have the permissions required to create users, they won’t be able to assign a role that contains these permissions. This is done to prevent escalation of privileges.
Example request
POST /api/access-control/teams/1/roles
Accept: application/json
Content-Type: application/json
{
"roleUid": "XvHQJq57z"
}
JSON body schema
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Role added to the team."
}
Status codes
Remove a team role assignment
DELETE /api/access-control/teams/:teams/roles/:roleUID
Revoke a role from a team.
For bulk updates consider Set team role assignments.
Required permissions
permissions:type:delegate
scope ensures that users can only unassign roles which have same, or a subset of permissions which the user has.
For example, if a user does not have the permissions required to create users, they won’t be able to assign a role that contains these permissions. This is done to prevent escalation of privileges.```
Example request
DELETE /api/access-control/teams/1/roles/AFUXBHKnk
Accept: application/json
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Role removed from team."
}
Status codes
Set team role assignments
PUT /api/access-control/teams/:teamId/roles
Update the team’s role assignments to match the provided set of UIDs. This will remove any assigned roles that aren’t in the request and add roles that are in the set but are not already assigned to the user.
If you want to add or remove a single role, consider using Add a team role assignment or Remove a team role assignment instead.
Required permissions
permissions:type:delegate
scope ensures that users can only assign or unassign roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won’t be able to assign or unassign a role to a team which will allow to do that. This is done to prevent escalation of privileges.
Example request
PUT /api/access-control/teams/1/roles
Accept: application/json
Content-Type: application/json
{
"roleUids": [
"ZiHQJq5nk",
"GzNQ1357k"
]
}
JSON body schema
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Team roles have been updated."
}
Status codes
Reset basic roles to their default
POST /api/access-control/roles/hard-reset
permissions:type:escalate
scope enables users to reset basic roles permissions.
This could result in basic roles having permissions exceedind those of callers.
Reset basic roles permissions to their default.
Required permissions
Example request
POST /api/access-control/roles/hard-reset
Accept: application/json
Content-Type: application/json
{
"BasicRoles": true
}
JSON body schema
Example response
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Reset performed"
}