Fine-grained access control API

Fine-grained access control API is only available in Grafana Enterprise. Read more about Grafana Enterprise.

The API can be used to create, update, get and list roles, and create or remove built-in role assignments. To use the API, you would need to enable fine-grained access control.

The API does not currently work with an API Token. So in order to use these API endpoints you will have to use Basic auth.

Get status

GET /api/access-control/status

Returns an indicator to check if fine-grained access control is enabled or not.

Required permissions

ActionScope
status:accesscontrolservices:accesscontrol

Example request

  1. GET /api/access-control/status
  2. Accept: application/json
  3. Content-Type: application/json

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. {
  4. "enabled": true
  5. }

Status codes

CodeDescription
200Returned a flag indicating if the fine-grained access control is enabled or no.
403Access denied
404Not found, an indication that fine-grained access control is not available at all.
500Unexpected error. Refer to body and/or server logs for more details.

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.

Refer to the Role scopes for more information.

Query Parameters:

  • includeHidden: Optional. Set to true to include roles that are hidden.

Required permissions

ActionScope
roles:listroles:*

Example request

  1. GET /api/access-control/roles
  2. Accept: application/json
  3. Content-Type: application/json

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. [
  4. {
  5. "version": 3,
  6. "uid": "XvHQJq57z",
  7. "name": "fixed:reports:reader",
  8. "displayName": "Report reader",
  9. "description": "Read all reports and shared report settings.",
  10. "group": "Reports",
  11. "updated": "2021-11-19T10:48:00+01:00",
  12. "created": "2021-11-19T10:48:00+01:00",
  13. "global": false
  14. },
  15. {
  16. "version": 5,
  17. "uid": "vi9mlLjGz",
  18. "name": "fixed:datasources.permissions:writer",
  19. "description: "Create, read or delete data source permissions.",
  20. "global": true,
  21. "updated": "2021-05-13T22:41:49+02:00",
  22. "created": "2021-05-13T16:24:26+02:00"
  23. }
  24. ]

Status codes

CodeDescription
200Global and organization local roles are returned.
403Access denied
500Unexpected error. Refer to body and/or server logs for more details.

Get a role

GET /api/access-control/roles/:uid

Get a role for the given UID.

Required permissions

ActionScope
roles:readroles:*

Example request

  1. GET /api/access-control/roles/PYnDO3rMk
  2. Accept: application/json
  3. Content-Type: application/json

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. {
  4. "version": 4,
  5. "uid": "6dNwJq57z",
  6. "name": "fixed:reports:writer",
  7. "displayName": "Report writer",
  8. "description": "Create, read, update, or delete all reports and shared report settings.",
  9. "group": "Reports",
  10. "permissions": [
  11. {
  12. "action": "reports:delete",
  13. "scope": "reports:*",
  14. "updated": "2021-11-19T10:48:00+01:00",
  15. "created": "2021-11-19T10:48:00+01:00"
  16. },
  17. {
  18. "action": "reports:read",
  19. "scope": "reports:*",
  20. "updated": "2021-11-19T10:48:00+01:00",
  21. "created": "2021-11-19T10:48:00+01:00"
  22. },
  23. {
  24. "action": "reports:send",
  25. "scope": "reports:*",
  26. "updated": "2021-11-19T10:48:00+01:00",
  27. "created": "2021-11-19T10:48:00+01:00"
  28. },
  29. {
  30. "action": "reports.admin:create",
  31. "scope": "",
  32. "updated": "2021-11-19T10:48:00+01:00",
  33. "created": "2021-11-19T10:48:00+01:00"
  34. },
  35. {
  36. "action": "reports.admin:write",
  37. "scope": "reports:*",
  38. "updated": "2021-11-19T10:48:00+01:00",
  39. "created": "2021-11-19T10:48:00+01:00"
  40. },
  41. {
  42. "action": "reports.settings:read",
  43. "scope": "",
  44. "updated": "2021-11-19T10:48:00+01:00",
  45. "created": "2021-11-19T10:48:00+01:00"
  46. },
  47. {
  48. "action": "reports.settings:write",
  49. "scope": "",
  50. "updated": "2021-11-19T10:48:00+01:00",
  51. "created": "2021-11-19T10:48:00+01:00"
  52. }
  53. ],
  54. "updated": "2021-11-19T10:48:00+01:00",
  55. "created": "2021-11-19T10:48:00+01:00",
  56. "global": false
  57. }

Status codes

CodeDescription
200Role is returned.
403Access denied.
500Unexpected error. Refer to body and/or server logs for more details.

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

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

ActionScope
roles:writepermissions:delegate

Example request

  1. POST /api/access-control/roles
  2. Accept: application/json
  3. Content-Type: application/json
  4. {
  5. "version": 1,
  6. "uid": "jZrmlLCGka",
  7. "name": "custom:delete:roles",
  8. "displayName": "custom delete roles",
  9. "description": "My custom role which gives users permissions to delete roles",
  10. "group":"My Group",
  11. "displayName": "My Custom Role",
  12. "global": false,
  13. "permissions": [
  14. {
  15. "action": "roles:delete",
  16. "scope": "permissions:delegate"
  17. }
  18. ]
  19. }

JSON body schema

Field NameDate TypeRequiredDescription
uidstringNoUID of the role. If not present, the UID will be automatically created for you and returned in response. Refer to the Custom roles for more information.
globalbooleanNoA flag indicating if the role is global or not. If set to false, the default org ID of the authenticated user will be used from the request. Refer to the Role scopes for more information.
versionnumberNoVersion of the role. If not present, version 0 will be assigned to the role and returned in the response. Refer to the Custom roles for more information.
namestringYesName of the role. Refer to Custom roles for more information.
descriptionstringNoDescription of the role.
displayNamestringNoDisplay name of the role, visible in the UI.
groupstringNoThe group name the role belongs to.
hiddenbooleanNoSpecify whether the role is hidden or not. If set to true, then the role does not show in the role picker. It will not be listed by API endpoints unless explicitly specified.
permissionsPermissionNoIf not present, the role will be created without any permissions.

Permission

Field NameData TypeRequiredDescription
actionstringYesRefer to Permissions for full list of available actions.
scopestringNoIf not present, no scope will be mapped to the permission. Refer to Permissions for full list of available scopes.

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. {
  4. "version": 2,
  5. "uid": "jZrmlLCGka",
  6. "name": "custom:delete:create:roles",
  7. "displayName": "custom delete create roles",
  8. "description": "My custom role which gives users permissions to delete and create roles",
  9. "group":"My Group",
  10. "displayName": "My Custom Role",
  11. "global": false,
  12. "permissions": [
  13. {
  14. "action": "roles:delete",
  15. "scope": "permissions:delegate",
  16. "updated": "2021-05-13T23:19:46+02:00",
  17. "created": "2021-05-13T23:19:46+02:00"
  18. }
  19. ],
  20. "updated": "2021-05-13T23:20:51.416518+02:00",
  21. "created": "2021-05-13T23:19:46+02:00"
  22. }

Status codes

CodeDescription
200Role is updated.
400Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403Access denied
500Unexpected error. Refer to body and/or server logs for more details.

Update a custom role

PUT /api/access-control/roles/:uid

Update the role with the given UID, and it’s permissions with the given UID. The operation is idempotent and all permissions of the role will be replaced with what is in the request. You would need to increment the version of the role with each update, otherwise the request will fail.

Required permissions

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

ActionScope
roles:writepermissions:delegate

Example request

  1. PUT /api/access-control/roles/jZrmlLCGka
  2. Accept: application/json
  3. Content-Type: application/json
  4. {
  5. "version": 3,
  6. "name": "custom:delete:write:roles",
  7. "displayName": "custom delete write roles",
  8. "description": "My custom role which gives users permissions to delete and write roles",
  9. "group":"My Group",
  10. "displayName": "My Custom Role",
  11. "global": false,
  12. "permissions": [
  13. {
  14. "action": "roles:delete",
  15. "scope": "permissions:delegate"
  16. },
  17. {
  18. "action": "roles:write",
  19. "scope": "permissions:delegate"
  20. }
  21. ]
  22. }

JSON body schema

Field NameData TypeRequiredDescription
versionnumberYesVersion of the role. Must be incremented for update to work.
namestringYesName of the role.
descriptionstringNoDescription of the role.
displayNamestringNoDisplay name of the role, visible in the UI.
groupstringNoThe group name the role belongs to.
hiddenbooleanNoSpecify whether the role is hidden or not. If set to true, then the role does not show in the role picker. It will not be listed by API endpoints unless explicitly specified.
permissionsList of PermissionsNoThe full list of permissions for the role after the update.

Permission

Field NameData TypeRequiredDescription
actionstringYesRefer to Permissions for full list of available actions.
scopestringNoIf not present, no scope will be mapped to the permission. Refer to Permissions for full list of available scopes.

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. {
  4. "version":3,
  5. "uid":"jZrmlLCGka",
  6. "name":"custom:delete:write:roles",
  7. "displayName":"custom delete write roles",
  8. "description":"My custom role which gives users permissions to delete and write roles",
  9. "group":"My Group",
  10. "displayName": "My Custom Role",
  11. "permissions":[
  12. {
  13. "action":"roles:delete",
  14. "scope":"permissions:delegate",
  15. "updated":"2021-08-06T18:27:40+02:00",
  16. "created":"2021-08-06T18:27:40+02:00"
  17. },
  18. {
  19. "action":"roles:write",
  20. "scope":"permissions:delegate",
  21. "updated":"2021-08-06T18:27:41+02:00",
  22. "created":"2021-08-06T18:27:41+02:00"
  23. }
  24. ],
  25. "updated":"2021-08-06T18:27:41+02:00",
  26. "created":"2021-08-06T18:27:40+02:00",
  27. "global":false
  28. }

Status codes

CodeDescription
200Role is updated.
400Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403Access denied
404Role was not found to update.
500Unexpected error. Refer to body and/or server logs for more details.

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 to a built-in role, the deletion operation will fail, unless force query param is set to true, and in that case all assignments will also be deleted.

Required permissions

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

ActionScope
roles:deletepermissions:delegate

Example request

  1. DELETE /api/access-control/roles/jZrmlLCGka?force=true&global=false
  2. Accept: application/json

Query parameters

ParamTypeRequiredDescription
forcebooleanNoWhen set to true, the role will be deleted with all it’s assignments.
globalbooleanNoA flag indicating if the role is global or not. If set to false, the default org ID of the authenticated user will be used from the request. Refer to the Role scopes for more information.

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. {
  4. "message": "Role deleted"
  5. }

Status codes

CodeDescription
200Role is deleted.
400Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403Access denied
500Unexpected error. Refer to body and/or server logs for more details.

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 built-in 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 to true to include roles that are hidden.

Required permissions

ActionScope
users.roles:listusers:id:<user ID>

Example request

  1. GET /api/access-control/users/1/roles
  2. Accept: application/json

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. [
  4. {
  5. "version": 4,
  6. "uid": "6dNwJq57z",
  7. "name": "fixed:reports:writer",
  8. "displayName": "Report writer",
  9. "description": "Create, read, update, or delete all reports and shared report settings.",
  10. "group": "Reports",
  11. "updated": "2021-11-19T10:48:00+01:00",
  12. "created": "2021-11-19T10:48:00+01:00",
  13. "global": false
  14. }
  15. ]

Status codes

CodeDescription
200Set of assigned roles is returned.
403Access denied.
500Unexpected error. Refer to body and/or server logs for more details.

List permissions assigned to a user

GET /api/access-control/users/:userId/permissions

Lists the permissions that a given user has.

Required permissions

ActionScope
users.permissions:listusers:id:<user ID>

Example request

  1. GET /api/access-control/users/1/permissions
  2. Accept: application/json

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. [
  4. {
  5. "action": "ldap.status:read",
  6. "scope": ""
  7. },
  8. {
  9. "action": "ldap.user:read",
  10. "scope": ""
  11. }
  12. ]

Status codes

CodeDescription
200Set of assigned permissions is returned.
403Access denied.
500Unexpected error. Refer to body and/or server logs for more details.

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

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

ActionScope
users.roles:addpermissions:delegate

Example request

  1. POST /api/access-control/users/1/roles
  2. Accept: application/json
  3. Content-Type: application/json
  4. {
  5. "global": false,
  6. "roleUid": "XvHQJq57z"
  7. }

JSON body schema

Field NameData TypeRequiredDescription
roleUidstringYesUID of the role.
globalbooleanNoA flag indicating if the assignment is global or not. If set to false, the default org ID of the authenticated user will be used from the request to create organization local assignment.

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. {
  4. "message": "Role added to the user."
  5. }

Status codes

CodeDescription
200Role is assigned to a user.
403Access denied.
404Role not found.
500Unexpected error. Refer to body and/or server logs for more details.

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

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

ActionScope
users.roles:removepermissions:delegate

Query parameters

ParamTypeRequiredDescription
globalbooleanNoA flag indicating if the assignment is global or not. If set to false, the default org ID of the authenticated user will be used from the request to remove assignment.

Example request

  1. DELETE /api/access-control/users/1/roles/AFUXBHKnk
  2. Accept: application/json

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. {
  4. "message": "Role removed from user."
  5. }

Status codes

CodeDescription
200Role is unassigned.
403Access denied.
500Unexpected error. Refer to body and/or server logs for more details.

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

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

ActionScope
users.roles:addpermissions:delegate
users.roles:removepermissions:delegate

Example request

  1. PUT /api/access-control/users/1/roles
  2. Accept: application/json
  3. Content-Type: application/json
  4. {
  5. "global": false,
  6. "roleUids": [
  7. "ZiHQJq5nk",
  8. "GzNQ1357k"
  9. ]
  10. }

JSON body schema

Field NameDate TypeRequiredDescription
globalbooleanNoA flag indicating if the assignment is global or not. If set to false, the default org ID of the authenticated user will be used from the request.
roleUidslistYesList of role UIDs.
includeHiddenbooleanNoSpecify whether the hidden role assignments should be updated.

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. {
  4. "message": "User roles have been updated."
  5. }

Status codes

CodeDescription
200Roles have been assigned.
403Access denied.
404Role not found.
500Unexpected error. Refer to body and/or server logs for more details.

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 to true to include roles that are hidden.

Required permissions

ActionScope
teams.roles:listteams:id:<team ID>

Example request

  1. GET /api/access-control/teams/1/roles
  2. Accept: application/json

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. [
  4. {
  5. "version": 4,
  6. "uid": "j08ZBi-nk",
  7. "name": "fixed:licensing:reader",
  8. "displayName": "Licensing reader",
  9. "description": "Read licensing information and licensing reports.",
  10. "group": "Licenses",
  11. "updated": "2022-02-03T14:19:50+01:00",
  12. "created": "0001-01-01T00:00:00Z",
  13. "global": false
  14. }
  15. ]

Status codes

CodeDescription
200Set of assigned roles is returned.
403Access denied.
500Unexpected error. Refer to body and/or server logs for more details.

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

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

ActionScope
teams.roles:addpermissions:delegate

Example request

  1. POST /api/access-control/teams/1/roles
  2. Accept: application/json
  3. Content-Type: application/json
  4. {
  5. "roleUid": "XvHQJq57z"
  6. }

JSON body schema

Field NameData TypeRequiredDescription
roleUidstringYesUID of the role.

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. {
  4. "message": "Role added to the team."
  5. }

Status codes

CodeDescription
200Role is assigned to a team.
403Access denied.
404Role not found.
500Unexpected error. Refer to body and/or server logs for more details.

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

permission: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.```

ActionScope
teams.roles:removepermissions:delegate

Example request

  1. DELETE /api/access-control/teams/1/roles/AFUXBHKnk
  2. Accept: application/json

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. {
  4. "message": "Role removed from team."
  5. }

Status codes

CodeDescription
200Role is unassigned.
403Access denied.
500Unexpected error. Refer to body and/or server logs for more details.

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

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

ActionScope
teams.roles:addpermissions:delegate
teams.roles:removepermissions:delegate

Example request

  1. PUT /api/access-control/teams/1/roles
  2. Accept: application/json
  3. Content-Type: application/json
  4. {
  5. "roleUids": [
  6. "ZiHQJq5nk",
  7. "GzNQ1357k"
  8. ]
  9. }

JSON body schema

Field NameDate TypeRequiredDescription
roleUidslistYesList of role UIDs.
includeHiddenbooleanNoSpecify whether the hidden role assignments should be updated.

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. {
  4. "message": "Team roles have been updated."
  5. }

Status codes

CodeDescription
200Roles have been assigned.
403Access denied.
404Role not found.
500Unexpected error. Refer to body and/or server logs for more details.

Create and remove built-in role assignments

API set allows to create or remove built-in role assignments and list current assignments.

Get all built-in role assignments

GET /api/access-control/builtin-roles

Gets all built-in role assignments.

Query Parameters:

  • includeHidden: Optional. Set to true to include roles that are hidden.

Required permissions

ActionScope
roles.builtin:listroles:*

Example request

  1. GET /api/access-control/builtin-roles
  2. Accept: application/json
  3. Content-Type: application/json

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. {
  4. "Admin": [
  5. {
  6. "version": 1,
  7. "uid": "qQui_LCMk",
  8. "name": "fixed:users:writer",
  9. "name": "User writer",
  10. "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",
  11. "global": true,
  12. "updated": "2021-05-13T16:24:26+02:00",
  13. "created": "2021-05-13T16:24:26+02:00"
  14. },
  15. {
  16. "version": 1,
  17. "uid": "PeXmlYjMk",
  18. "name": "fixed:users:reader",
  19. "displayName": "User reader",
  20. "description": "Allows every read action for user organizations and in addition allows to administer user organizations",
  21. "global": true,
  22. "updated": "2021-05-13T16:24:26+02:00",
  23. "created": "2021-05-13T16:24:26+02:00"
  24. }
  25. ],
  26. "Grafana Admin": [
  27. {
  28. "version": 1,
  29. "uid": "qQui_LCMk",
  30. "name": "fixed:users:writer",
  31. "displayName": "User writer",
  32. "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",
  33. "global": true,
  34. "updated": "2021-05-13T16:24:26+02:00",
  35. "created": "2021-05-13T16:24:26+02:00"
  36. }
  37. ]
  38. }

Status codes

CodeDescription
200Built-in role assignments are returned.
403Access denied
500Unexpected error. Refer to body and/or server logs for more details.

Create a built-in role assignment

POST /api/access-control/builtin-roles

Creates a new built-in role assignment.

Required permissions

permission:delegate scope ensures that users can only create built-in role assignments with the 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 create a built-in role assignment which will allow to do that. This is done to prevent escalation of privileges.

ActionScope
roles.builtin:addpermissions:delegate

Example request

  1. POST /api/access-control/builtin-roles
  2. Accept: application/json
  3. Content-Type: application/json
  4. {
  5. "roleUid": "LPMGN99Mk",
  6. "builtinRole": "Grafana Admin",
  7. "global": false
  8. }

JSON body schema

Field NameDate TypeRequiredDescription
roleUidstringYesUID of the role.
builtinRolebooleanYesCan be one of Viewer, Editor, Admin or Grafana Admin.
globalbooleanNoA flag indicating if the assignment is global or not. If set to false, the default org ID of the authenticated user will be used from the request to create organization local assignment. Refer to the Built-in role assignments for more information.

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. {
  4. "message": "Built-in role grant added"
  5. }

Status codes

CodeDescription
200Role was assigned to built-in role.
400Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403Access denied
404Role not found
500Unexpected error. Refer to body and/or server logs for more details.

Remove a built-in role assignment

DELETE /api/access-control/builtin-roles/:builtinRole/roles/:roleUID

Deletes a built-in role assignment (for one of Viewer, Editor, Admin, or Grafana Admin) to the role with the provided UID.

Required permissions

permission:delegate scope ensures that users can only remove built-in role assignments with the 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 remove a built-in role assignment which allows to do that.

ActionScope
roles.builtin:removepermissions:delegate

Example request

  1. DELETE /api/access-control/builtin-roles/Grafana%20Admin/roles/LPMGN99Mk?global=false
  2. Accept: application/json

Query parameters

ParamTypeRequiredDescription
globalbooleanNoA flag indicating if the assignment is global or not. If set to false, the default org ID of the authenticated user will be used from the request to remove assignment. Refer to the Built-in role assignments for more information.

Example response

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json; charset=UTF-8
  3. {
  4. "message": "Built-in role grant removed"
  5. }

Status codes

CodeDescription
200Role was unassigned from built-in role.
400Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403Access denied
404Role not found.
500Unexpected error. Refer to body and/or server logs for more details.