Fine-grained access control API

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 .

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

Example request

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
  "enabled": true
}

Status codes

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 for more information.

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": 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

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "uid": "6dNwJq57z",
    "name": "fixed:reports:writer",
    "displayName": "Report writer",
    "description": "Create, read, update, or delete all reports and shared report settings.",
    "group": "Reports",
    "permissions": [
        {
            "action": "reports:delete",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports:read",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports:send",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports.admin:create",
            "scope": "",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports.admin:write",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports.settings:read",
            "scope": "",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports.settings:write",
            "scope": "",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        }
    ],
    "updated": "2021-11-19T10:48:00+01:00",
    "created": "2021-11-19T10:48:00+01:00",
    "global": false
}

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

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.

Example request

POST /api/access-control/roles
Accept: application/json
Content-Type: application/json
{
    "version": 1,
    "uid": "jZrmlLCGka",
    "name": "custom:delete:roles",
    "group":"My Group",
    "displayName": "My Custom Role",
    "global": false,
    "permissions": [
        {
            "action": "roles:delete",
            "scope": "permissions: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",
    "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: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

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

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.

Example request

PUT /api/access-control/roles/jZrmlLCGka
Accept: application/json
Content-Type: application/json
{
    "version": 3,
    "name": "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:delegate"
        },
        {
            "action": "roles:write",
            "scope": "permissions:delegate"
        }
    ]
}

JSON body schema

Permission

Example response

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

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

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.

Required permissions

Example request

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 user

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

Lists the permissions that a given user 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

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.

Example request

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

DELETE /api/access-control/users/:userId/roles/:roleUID

For bulk updates consider .

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.

Query parameters

Example request

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

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

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.

Required permissions

Example request

GET /api/access-control/builtin-roles
Accept: application/json
Content-Type: application/json

Example response

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
    "Admin": [
        {
            "version": 1,
            "uid": "qQui_LCMk",
            "name": "fixed:users:org:edit",
            "description": "",
            "global": false,
            "updated": "2021-05-13T16:24:26+02:00",
            "created": "2021-05-13T16:24:26+02:00"
        },
        {
            "version": 1,
            "uid": "PeXmlYjMk",
            "name": "fixed:users:org:read",
            "description": "",
            "global": false,
            "updated": "2021-05-13T16:24:26+02:00",
            "created": "2021-05-13T16:24:26+02:00"
        }
    ],
    "Grafana Admin": [
        {
            "version": 1,
            "uid": "qQui_LCMk",
            "name": "fixed:users:org:edit",
            "description": "",
            "global": false,
            "updated": "2021-05-13T16:24:26+02:00",
            "created": "2021-05-13T16:24:26+02:00"
        }
    ]
}

Status codes

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.

Example request

POST /api/access-control/builtin-roles
Accept: application/json
Content-Type: application/json
{
    "roleUid": "LPMGN99Mk",
    "builtinRole": "Grafana Admin",
    "global": false
}

JSON body schema

Example response

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

Status codes

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

Example request

DELETE /api/access-control/builtin-roles/Grafana%20Admin/roles/LPMGN99Mk?global=false

Query parameters

Example response

Status codes