Project: Grafana (Observability and Analysis / Observability)
File: access_control.md

aliases: ../../httpapi/accesscontrol/ ../../http_api/accesscontrol/ canonical: /docs/grafana/latest/developers/httpapi/accesscontrol/ description: '' keywords: grafana http documentation api role-based-access-control acl enterprise labels: products: enterprise oss title: RBAC HTTP API Role-based access control API is only available in Grafana Cloud or Grafana Enterprise. Read more about . 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 . `GET /api/access-control/status` Returns an indicator to check if role-based access control is enabled or not. | Action | Scope | | -- | - | | status:accesscontrol | services:accesscontrol | ```http GET /api/access-control/status Accept: application/json Content-Type: application/json ``` ```http HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "enabled": true } ``` | Code | Description | | - | -- | | 200 | Returned a flag indicating if the role-based access control is enabled or no. | | 403 | Access denied | | 404 | Not found, an indication that role-based access control is not available at all. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `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 to `true` to include roles that are `hidden`. | Action | Scope | | - | -- | | roles:read | roles:\* | ```http GET /api/access-control/roles Accept: application/json Content-Type: application/json ``` ```http 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" } ] ``` | Code | Description | | - | -- | | 200 | Global and organization local roles are returned. | | 403 | Access denied | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `GET /api/access-control/roles/:uid` Get a role for the given UID. | Action | Scope | | - | -- | | roles:read | roles:\* | ```http GET /api/access-control/roles/PYnDO3rMk Accept: application/json Content-Type: application/json ``` ```http 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", "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:create", "scope": "", "updated": "2021-11-19T10:48:00+01:00", "created": "2021-11-19T10:48:00+01:00" }, { "action": "reports: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 } ``` | Code | Description | | - | -- | | 200 | Role is returned. | | 403 | Access denied. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `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 can't be

`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. | Action | Scope | | -- | - | | roles:write | permissions:type:delegate | ```http 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" } ] } ``` | Field Name | Date Type | Required | Description | | -- | - | -- | -- | | uid | string | No | UID of the role. If not present, the UID will be automatically created for you and returned in response. Refer to the for more information. | | global | boolean | No | A 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. | | version | number | No | Version of the role. If not present, version 0 will be assigned to the role and returned in the response. Refer to the for more information. | | name | string | Yes | Name of the role. Refer to for more information. | | description | string | No | Description of the role. | | displayName | string | No | Display name of the role, visible in the UI. | | group | string | No | The group name the role belongs to. | | hidden | boolean | No | Specify 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. | | permissions | Permission | No | If not present, the role will be created without any permissions. | Permission | Field Name | Data Type | Required | Description | | - | | -- | - | | action | string | Yes | Refer to for full list of available actions. | | scope | string | No | If not present, no scope will be mapped to the permission. Refer to for full list of available scopes. | ```http 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" } ``` Permission validation only occurs when permission validation is enabled (`rbac.permissionvalidationenabled = true`). It has been enabled by default since Grafana 10.2. The following example shows a request with an invalid action. The action `serviceaccounts.permissions:reader` is not a valid action. The valid action should be `serviceaccounts.permissions:read`. ```http POST /api/access-control/roles HTTP/1.1 Content-Type: application/json { "Name": "Read Service Account with id 6", "Permissions": [ { "action": "serviceaccounts.permissions:reader", "scope": "serviceaccounts:uid:6" } ] } ``` ```http

400 Bad Request Content-Type: application/json { "extra": { "validationError": "the provided action was not found in the list of valid actions: serviceaccounts.permissions:reader" }, "message": "Permission contains an invalid action", "messageId": "accesscontrol.permission-invalid-action", "statusCode": 400, "traceID": "" } ``` The following example shows a request with an invalid scope. The scope `serviceaccounts:serviceaccount6` is not a valid scope for the action `serviceaccounts.permissions:read`. The valid scopes for this action are ``, `serviceaccounts:` and `serviceaccounts:id:*`. ```http POST /api/access-control/roles HTTP/1.1 Content-Type: application/json { "Name": "Read Service Account with id 6", "Permissions": [ { "action": "serviceaccounts.permissions:read", "scope": "serviceaccounts:serviceaccount6" } ] } ``` ```http HTTP/1.1 400 Bad Request Content-Type: application/json { "extra": { "validationError": "unknown scope: serviceaccounts:serviceaccount6 for action: serviceaccounts.permissions:read provided, expected prefixes are [ serviceaccounts: serviceaccounts:id:*]" }, "message": "Invalid scope", "messageId": "accesscontrol.permission-invalid-scope", "statusCode": 400, "traceID": "" } ``` | Code | Description | | - | - | | 200 | Role is updated. | | 400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.). | | 403 | Access denied (one of the specified permissions is not assigned to the requester) | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `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. `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. | Action | Scope | | -- | - | | roles:write | permissions:type:delegate | ```http 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" } ] } ``` | Field Name | Data Type | Required | Description | | -- | - | -- | -- | | version | number | Yes | Version of the role. Must be incremented for update to work. | | name | string | Yes | Name of the role. | | description | string | No | Description of the role. | | displayName | string | No | Display name of the role, visible in the UI. | | group | string | No | The group name the role belongs to. | | hidden | boolean | No | Specify 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. | | permissions | List of Permissions | No | The full list of permissions for the role after the

| Permission | Field Name | Data Type | Required | Description | | - | | -- | - | | action | string | Yes | Refer to for full list of available actions. | | scope | string | No | If not present, no scope will be mapped to the permission. Refer to for full list of available scopes. | ```http 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 } ``` Permission validation only occurs when permission validation is enabled (`rbac.permissionvalidationenabled = true`). It has been enabled by default since Grafana 10.2. For more information, refer to . | Code | Description | | - | - | | 200 | Role is updated. | | 400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.). | | 403 | Access denied (one of the specified permissions is not assigned to the requester) | | 404 | Role was not found to update. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `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. `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. | Action | Scope | | | - | | roles:delete | permissions:type:delegate | ```http DELETE /api/access-control/roles/jZrmlLCGka?force=true&global=false Accept: application/json ``` | Param | Type | Required | Description | | | - | -- | | | force | boolean | No | When set to `true`, the role will be deleted with all its assignments. | | global | boolean | No | A 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 for more information. | ```http HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "message": "Role deleted" } ``` | Code | Description | | - | - | | 200 | Role is deleted. | | 400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.). | | 403 | Access denied | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `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 to `true` to include roles that are `hidden`. | Action | Scope | | - | -- | | users.roles:read | users:id:`<user ID>` | ```http GET /api/access-control/users/1/roles Accept: application/json ``` ```http 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

"group": "Reports", "updated": "2021-11-19T10:48:00+01:00", "created": "2021-11-19T10:48:00+01:00", "global": false } ] ``` | Code | Description | | - | -- | | 200 | Set of assigned roles is returned. | | 403 | Access denied. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `GET /api/access-control/user/permissions` Lists the permissions granted to the signed in user. No permission is required. | Param | Type | Required | Description | | -- | - | -- | -- | | reloadcache | boolean | No | A flag to reload the permission cache. | ```http GET /api/access-control/user/permissions Accept: application/json ``` ```http 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": [""] } ``` | Code | Description | | - | -- | | 200 | Set of assigned permissions is returned. | | 403 | Access denied. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `GET /api/access-control/users/:userId/permissions` Lists the permissions granted to a given user. | Action | Scope | | - | -- | | users.permissions:read | users:id:`<user ID>` | ```http GET /api/access-control/users/1/permissions Accept: application/json ``` ```http HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 [ { "action": "ldap.status:read", "scope": "" }, { "action": "ldap.user:read", "scope": "" } ] ``` | Code | Description | | - | -- | | 200 | Set of assigned permissions is returned. | | 403 | Access denied. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `POST /api/access-control/users/:userId/roles` Assign a role to a specific user. For bulk updates consider . `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. | Action | Scope | | | - | | users.roles:add | permissions:type:delegate | ```http POST /api/access-control/users/1/roles Accept: application/json Content-Type: application/json { "global": false, "roleUid": "XvHQJq57z" } ``` | Field Name | Data Type | Required | Description | | - | | -- | -- | | roleUid | string | Yes | UID of the role. | | global | boolean | No | A 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. | ```http HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "message": "Role added to the user." } ``` | Code | Description | | - | -- | | 200 | Role is assigned to a user. | | 403 | Access denied. | | 404 | Role not found. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `DELETE /api/access-control/users/:userId/roles/:roleUID` Revoke a role from a user. For bulk updates consider . `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

| Action | Scope | | | - | | users.roles:remove | permissions:type:delegate | | Param | Type | Required | Description | | | - | -- | - | | global | boolean | No | A 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. | ```http DELETE /api/access-control/users/1/roles/AFUXBHKnk Accept: application/json ``` ```http HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "message": "Role removed from user." } ``` | Code | Description | | - | -- | | 200 | Role is unassigned. | | 403 | Access denied. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `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 or instead. `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. | Action | Scope | | | - | | users.roles:add | permissions:type:delegate | | users.roles:remove | permissions:type:delegate | ```http PUT /api/access-control/users/1/roles Accept: application/json Content-Type: application/json { "global": false, "roleUids": [ "ZiHQJq5nk", "GzNQ1357k" ] } ``` | Field Name | Date Type | Required | Description | | - | | -- | - | | global | boolean | No | A 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. | | roleUids | list | Yes | List of role UIDs. | | includeHidden | boolean | No | Specify whether the hidden role assignments should be updated. | ```http HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "message": "User roles have been updated." } ``` | Code | Description | | - | -- | | 200 | Roles have been assigned. | | 403 | Access denied. | | 404 | Role not found. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `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 to `true` to include roles that are `hidden`. | Action | Scope | | - | - | | users.roles:read | users:id:`<service account ID>` | ```http GET /api/access-control/users/1/roles Accept: application/json ``` ```http 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 } ] ``` | Code | Description | | - | -- | | 200 | Set of assigned roles is returned. | | 403 | Access denied. | | 500 | Unexpected

Refer to body and/or server logs for more details. | `GET /api/access-control/users/:serviceAccountId/permissions` Lists the permissions that a given service account has. | Action | Scope | | - | - | | users.permissions:read | users:id:`<service account ID>` | ```http GET /api/access-control/users/1/permissions Accept: application/json ``` ```http HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 [ { "action": "ldap.status:read", "scope": "" }, { "action": "ldap.user:read", "scope": "" } ] ``` | Code | Description | | - | -- | | 200 | Set of assigned permissions is returned. | | 403 | Access denied. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `POST /api/access-control/users/:serviceAccountId/roles` Assign a role to a specific service account. For bulk updates consider . `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. | Action | Scope | | | - | | users.roles:add | permissions:type:delegate | ```http POST /api/access-control/users/1/roles Accept: application/json Content-Type: application/json { "global": false, "roleUid": "XvHQJq57z" } ``` | Field Name | Data Type | Required | Description | | - | | -- | -- | | roleUid | string | Yes | UID of the role. | | global | boolean | No | A 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. | ```http HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "message": "Role added to the user." } ``` | Code | Description | | - | -- | | 200 | Role is assigned to a user. | | 403 | Access denied. | | 404 | Role not found. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `DELETE /api/access-control/users/:serviceAccountId/roles/:roleUID` Revoke a role from a service account. For bulk updates consider . `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. | Action | Scope | | | - | | users.roles:remove | permissions:type:delegate | | Param | Type | Required | Description | | | - | -- | - | | global | boolean | No | A 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. | ```http DELETE /api/access-control/users/1/roles/AFUXBHKnk Accept: application/json ``` ```http HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "message": "Role removed from user." } ``` | Code | Description | | - | -- | | 200 | Role is unassigned. | | 403 | Access denied. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `PUT /api/access-control/users/:serviceAccountId/roles` Update the service accounts's role assignments to match the provided set of

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 or instead. `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. | Action | Scope | | | - | | users.roles:add | permissions:type:delegate | | users.roles:remove | permissions:type:delegate | ```http PUT /api/access-control/users/1/roles Accept: application/json Content-Type: application/json { "global": false, "roleUids": [ "ZiHQJq5nk", "GzNQ1357k" ] } ``` | Field Name | Date Type | Required | Description | | - | | -- | - | | global | boolean | No | A 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. | | roleUids | list | Yes | List of role UIDs. | | includeHidden | boolean | No | Specify whether the hidden role assignments should be updated. | ```http HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "message": "User roles have been updated." } ``` | Code | Description | | - | -- | | 200 | Roles have been assigned. | | 403 | Access denied. | | 404 | Role not found. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `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`. | Action | Scope | | - | -- | | teams.roles:read | teams:id:`<team ID>` | ```http GET /api/access-control/teams/1/roles Accept: application/json ``` ```http 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 } ] ``` | Code | Description | | - | -- | | 200 | Set of assigned roles is returned. | | 403 | Access denied. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `POST /api/access-control/teams/:teamId/roles` Assign a role to a specific team. For bulk updates consider . `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. | Action | Scope | | | - | | teams.roles:add | permissions:type:delegate | ```http POST /api/access-control/teams/1/roles Accept: application/json Content-Type: application/json { "roleUid": "XvHQJq57z" } ``` | Field Name | Data Type | Required | Description | | - | | -- | - | | roleUid | string | Yes | UID of the role. | ```http HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "message": "Role added to the

} ``` | Code | Description | | - | -- | | 200 | Role is assigned to a team. | | 403 | Access denied. | | 404 | Role not found. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `DELETE /api/access-control/teams/:teams/roles/:roleUID` Revoke a role from a team. For bulk updates consider . `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.``` | Action | Scope | | | - | | teams.roles:remove | permissions:type:delegate | ```http DELETE /api/access-control/teams/1/roles/AFUXBHKnk Accept: application/json ``` ```http HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "message": "Role removed from team." } ``` | Code | Description | | - | -- | | 200 | Role is unassigned. | | 403 | Access denied. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `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 or instead. `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. | Action | Scope | | | - | | teams.roles:add | permissions:type:delegate | | teams.roles:remove | permissions:type:delegate | ```http PUT /api/access-control/teams/1/roles Accept: application/json Content-Type: application/json { "roleUids": [ "ZiHQJq5nk", "GzNQ1357k" ] } ``` | Field Name | Date Type | Required | Description | | - | | -- | -- | | roleUids | list | Yes | List of role UIDs. | | includeHidden | boolean | No | Specify whether the hidden role assignments should be updated. | ```http HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "message": "Team roles have been updated." } ``` | Code | Description | | - | -- | | 200 | Roles have been assigned. | | 403 | Access denied. | | 404 | Role not found. | | 500 | Unexpected error. Refer to body and/or server logs for more details. | `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. | Action | Scope | | -- | - | | roles:write | permissions:type:escalate | ```http POST /api/access-control/roles/hard-reset Accept: application/json Content-Type: application/json { "BasicRoles": true } ``` | Field Name | Data Type | Required | Description | | - | | -- | - | | BasicRoles | boolean | No | Option to reset basic roles permissions. | ```http HTTP/1.1 200 OK Content-Type: application/json; charset=UTF-8 { "message": "Reset performed" } ``` | Code | Description | | - | | | 200 | Reset performed | | 500 | Failed to reset basic roles |