菜单
文档面包屑箭头 Grafana 文档面包屑箭头 开发者面包屑箭头 HTTP API面包屑箭头 RBAC HTTP API
企业版 开源版

RBAC API

基于角色的访问控制 API 仅在 Grafana Cloud 或 Grafana Enterprise 中可用。了解更多关于 Grafana Enterprise 的信息。

该 API 可用于创建、更新、删除、获取和列出角色。

要查看哪些基本角色或固定角色拥有所需权限，请参阅 RBAC 角色定义。

获取状态

GET /api/access-control/status

返回一个指示器，用于检查基于角色的访问控制是否启用。

所需权限

操作范围
status:accesscontrolservices: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
}

状态码

状态码描述
200返回一个标志，指示基于角色的访问控制是否启用。
403访问被拒绝
404未找到，表示基于角色的访问控制完全不可用。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

创建和管理自定义角色

获取所有角色

GET /api/access-control/roles

获取所有现有角色。响应包含当前登录用户所在组织的所有全局角色和组织本地角色。

查询参数

  • includeHidden：可选。设为 true 以包含 隐藏 的角色。

所需权限

操作范围
roles:readroles:*

请求示例

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"
    }
]

状态码

状态码描述
200返回全局角色和组织本地角色。
403访问被拒绝
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

获取角色

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

获取给定 UID 的角色。

所需权限

操作范围
roles:readroles:*

请求示例

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
}

状态码

状态码描述
200角色已返回。
403访问被拒绝。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

创建新的自定义角色

POST /api/access-control/roles

创建一个新的自定义角色，并将给定的权限映射到该角色。请注意，不能创建与固定角色前缀相同的角色。

所需权限

permissions:type:delegate 范围确保用户只能创建具有其自身权限相同或子集的自定义角色。例如，如果用户没有创建用户所需的权限，他们将无法创建允许执行此操作的自定义角色。这样做是为了防止权限升级。

操作范围
roles:writepermissions: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"
        }
    ]
}

JSON 请求体 schema

字段名称数据类型必需描述
uidstring否角色的 UID。如果不存在，将自动为您创建 UID 并在响应中返回。有关更多信息，请参阅自定义角色。
globalboolean否一个标志，指示角色是否为全局角色。如果设置为 false，将使用请求中认证用户的默认组织 ID。
versionnumber否角色版本。如果不存在，将为角色分配版本 0 并在响应中返回。有关更多信息，请参阅自定义角色。
namestring是角色的名称。有关更多信息，请参阅自定义角色。
descriptionstring否角色的描述。
displayNamestring否角色的显示名称，在 UI 中可见。
groupstring否角色所属的组名称。
hiddenboolean否指定角色是否隐藏。如果设置为 true，则角色不会在角色选择器中显示。除非明确指定，否则 API 端点不会列出它。
permissions权限否如果不存在，将创建不带任何权限的角色。

权限

字段名称数据类型必需描述
actionstring是有关可用操作的完整列表，请参阅自定义角色操作和范围。
scopestring否如果不存在，则不会映射范围到权限。有关可用范围的完整列表，请参阅自定义角色操作和范围。

响应示例

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

创建角色验证错误

权限验证仅在启用权限验证（rbac.permission_validation_enabled = true）时发生。

自 Grafana 10.2 起默认启用。

无效操作

以下示例显示了一个包含无效操作的请求。操作 serviceaccounts.permissions:reader 是无效操作。有效操作应为 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 
HTTP/1.1 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": ""
}
无效范围

以下示例显示了一个包含无效范围的请求。范围 serviceaccounts:serviceaccount6 对于操作 serviceaccounts.permissions:read 无效。此操作的有效范围为 *、serviceaccounts:* 和 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": ""
}

状态码

状态码描述
200角色已更新。
400错误请求（json 无效、缺少 content-type、字段缺失或无效等）。
403访问被拒绝（请求者未被分配其中一个指定的权限）
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

更新角色

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

更新给定 UID 的角色及其权限。该操作是幂等的，角色的所有权限将根据请求内容被替换。每次更新都需要增加角色版本，否则请求将失败。

您可以更新 custom 角色和 basic 角色的权限。但是 fixed 角色不能被更新。

所需权限

permissions:type:delegate 范围确保用户只能更新具有其自身权限相同或子集的自定义角色。例如，如果用户没有创建用户所需的权限，他们将无法更新允许执行此操作的自定义角色。这样做是为了防止权限升级。

操作范围
roles:writepermissions: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"
        }
    ]
}

JSON 请求体 schema

字段名称数据类型必需描述
versionnumber是角色版本。必须递增以使更新生效。
namestring是角色名称。
descriptionstring否角色的描述。
displayNamestring否角色的显示名称，在 UI 中可见。
groupstring否角色所属的组名称。
hiddenboolean否指定角色是否隐藏。如果设置为 true，则角色不会在角色选择器中显示。除非明确指定，否则 API 端点不会列出它。
permissions权限列表否更新后角色的完整权限列表。

权限

字段名称数据类型必需描述
actionstring是有关可用操作的完整列表，请参阅自定义角色操作和范围。
scopestring否如果不存在，则不会映射范围到权限。有关可用范围的完整列表，请参阅自定义角色操作和范围。

响应示例

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
}

更新角色验证错误

权限验证仅在启用权限验证（rbac.permission_validation_enabled = true）时发生。

自 Grafana 10.2 起默认启用。

有关更多信息，请参阅创建角色验证错误。

状态码

状态码描述
200角色已更新。
400错误请求（json 无效、缺少 content-type、字段缺失或无效等）。
403访问被拒绝（请求者未被分配其中一个指定的权限）
404未找到要更新的角色。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

删除自定义角色

DELETE /api/access-control/roles/:uid?force=false

删除给定 UID 的角色及其权限。如果该角色已被分配，删除操作将失败，除非将查询参数 force 设置为 true，在这种情况下，所有分配也将被删除。

所需权限

permissions:type:delegate 范围确保用户只能删除具有其自身权限相同或子集的自定义角色。例如，如果用户没有创建用户所需的权限，他们将无法删除允许执行此操作的自定义角色。

操作范围
roles:deletepermissions:type:delegate

请求示例

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

查询参数

参数类型必需描述
forceboolean否设置为 true 时，角色及其所有分配将被删除。
globalboolean否一个标志，指示角色是否为全局角色。如果设置为 false，将使用请求中认证用户的默认组织 ID。有关更多信息，请参阅关于 RBAC。

响应示例

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role deleted"
}

状态码

状态码描述
200角色已删除。
400错误请求（json 无效、缺少 content-type、字段缺失或无效等）。
403访问被拒绝
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

创建和移除用户角色分配

列出分配给用户的角色

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

列出直接分配给给定用户的角色。列表不包含基本角色（Viewer、Editor、Admin 或 Grafana Admin），也不包含从团队继承的角色。

查询参数

  • includeHidden：可选。设为 true 以包含 隐藏 的角色。
  • includeMapped：可选。设为 true 以包含通过组属性同步功能映射的角色。

所需权限

操作范围
users.roles:readusers:id:<用户 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
    }
]

状态码

状态码描述
200返回分配的角色集合。
403访问被拒绝。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

列出您的权限

GET /api/access-control/user/permissions

列出授予已登录用户的权限。

所需权限

无需权限。

查询参数

参数类型必需描述
reloadcacheboolean否一个标志，用于重新加载权限缓存。

请求示例

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": [""]
}

状态码

状态码描述
200返回分配的权限集合。
403访问被拒绝。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

列出分配给用户的权限

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

列出授予给定用户的权限。

所需权限

操作范围
users.permissions:readusers:id:<用户 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": ""
    }
]

状态码

状态码描述
200返回分配的权限集合。
403访问被拒绝。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

添加用户角色分配

POST /api/access-control/users/:userId/roles

将角色分配给指定用户。

对于批量更新，请考虑设置用户角色分配。

所需权限

permissions:type:delegate 范围确保用户只能分配具有其自身权限相同或子集的角色。例如，如果用户没有创建用户所需的权限，他们将无法分配允许执行此操作的角色。这样做是为了防止权限升级。

操作范围
users.roles:addpermissions:type:delegate

请求示例

http 
POST /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json

{
    "global": false,
    "roleUid": "XvHQJq57z"
}

JSON 请求体 schema

字段名称数据类型必需描述
roleUidstring是角色的 UID。
globalboolean否一个标志，指示分配是否为全局分配。如果设置为 false，将使用请求中认证用户的默认组织 ID 创建组织本地分配。

响应示例

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role added to the user."
}

状态码

状态码描述
200角色已分配给用户。
403访问被拒绝。
404角色未找到。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

移除用户角色分配

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

从用户收回（移除）角色。

对于批量更新，请考虑设置用户角色分配。

所需权限

permissions:type:delegate 范围确保用户只能取消分配具有其自身权限相同或子集的角色。例如，如果用户没有创建用户所需的权限，他们将无法取消分配允许执行此操作的角色。这样做是为了防止权限升级。

操作范围
users.roles:removepermissions:type:delegate

查询参数

参数类型必需描述
globalboolean否一个标志，指示分配是否为全局分配。如果设置为 false，将使用请求中认证用户的默认组织 ID 移除分配。

请求示例

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

状态码

状态码描述
200角色已取消分配。
403访问被拒绝。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

设置用户角色分配

PUT /api/access-control/users/:userId/roles

更新用户的角色分配，使其与提供的 UID 集合匹配。这将移除请求中未包含的已分配角色，并添加集合中但尚未分配给用户的角色。

如果您想添加或移除单个角色，请考虑使用添加用户角色分配或移除用户角色分配。

所需权限

permissions:type:delegate 范围确保用户只能分配或取消分配具有其自身权限相同或子集的角色。例如，如果用户没有创建用户所需的权限，他们将无法分配或取消分配允许执行此操作的角色。这样做是为了防止权限升级。

操作范围
users.roles:addpermissions:type:delegate
users.roles:removepermissions:type:delegate

请求示例

http 
PUT /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json

{
    "global": false,
    "roleUids": [
        "ZiHQJq5nk",
        "GzNQ1357k"
    ]
}

JSON 请求体 schema

字段名称数据类型必需描述
globalboolean否一个标志，指示分配是否为全局分配。如果设置为 false，将使用请求中认证用户的默认组织 ID。
roleUidslist是角色 UID 列表。
includeHiddenboolean否指定是否应更新隐藏的角色分配。

响应示例

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "User roles have been updated."
}

状态码

状态码描述
200角色已分配。
403访问被拒绝。
404角色未找到。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

创建和移除服务账号角色分配

列出分配给服务账号的角色

GET /api/access-control/users/:serviceAccountId/roles

列出直接分配给给定服务账号的角色。列表不包含基本角色（Viewer、Editor、Admin 或 Grafana Admin）。

查询参数

  • includeHidden：可选。设为 true 以包含 隐藏 的角色。

所需权限

操作范围
users.roles:readusers:id:<服务账号 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
    }
]

状态码

状态码描述
200返回分配的角色集合。
403访问被拒绝。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

列出分配给服务账号的权限

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

列出给定服务账号拥有的权限。

所需权限

操作范围
users.permissions:readusers:id:<服务账号 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": ""
    }
]

状态码

状态码描述
200返回分配的权限集合。
403访问被拒绝。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

添加服务账号角色分配

POST /api/access-control/users/:serviceAccountId/roles

将角色分配给指定服务账号。

对于批量更新，请考虑设置服务账号角色分配。

所需权限

permissions:type:delegate 范围确保用户只能分配具有其自身权限相同或子集的角色。例如，如果用户没有创建用户所需的权限，他们将无法分配允许执行此操作的角色。这样做是为了防止权限升级。

操作范围
users.roles:addpermissions:type:delegate

请求示例

http 
POST /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json

{
    "global": false,
    "roleUid": "XvHQJq57z"
}

JSON 请求体 schema

字段名称数据类型必需描述
roleUidstring是角色的 UID。
globalboolean否一个标志，指示分配是否为全局分配。如果设置为 false，将使用请求中认证用户的默认组织 ID 创建组织本地分配。

响应示例

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role added to the user."
}

状态码

状态码描述
200角色已分配给用户。
403访问被拒绝。
404角色未找到。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

移除服务账号角色分配

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

从服务账号收回（移除）角色。

对于批量更新，请考虑设置服务账号角色分配。

所需权限

permissions:type:delegate 范围确保用户只能取消分配具有其自身权限相同或子集的角色。例如，如果用户没有创建用户所需的权限，他们将无法取消分配允许执行此操作的角色。这样做是为了防止权限升级。

操作范围
users.roles:removepermissions:type:delegate

查询参数

参数类型必需描述
globalboolean否一个标志，指示分配是否为全局分配。如果设置为 false，将使用请求中认证用户的默认组织 ID 移除分配。

请求示例

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

状态码

状态码描述
200角色已取消分配。
403访问被拒绝。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

设置服务账号角色分配

PUT /api/access-control/users/:serviceAccountId/roles

更新服务账号的角色分配，使其与提供的 UID 集合匹配。这将移除请求中未包含的已分配角色，并添加集合中但尚未分配给服务账号的角色。

如果您想添加或移除单个角色，请考虑使用添加服务账号角色分配或移除服务账号角色分配。

所需权限

permissions:type:delegate 范围确保用户只能分配或取消分配具有其自身权限相同或子集的角色。例如，如果用户没有创建用户所需的权限，他们将无法分配或取消分配允许执行此操作的角色。这样做是为了防止权限升级。

操作范围
users.roles:addpermissions:type:delegate
users.roles:removepermissions:type:delegate

请求示例

http 
PUT /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json

{
    "global": false,
    "roleUids": [
        "ZiHQJq5nk",
        "GzNQ1357k"
    ]
}

JSON 请求体 schema

字段名称数据类型必需描述
globalboolean否一个标志，指示分配是否为全局分配。如果设置为 false，将使用请求中认证用户的默认组织 ID。
roleUidslist是角色 UID 列表。
includeHiddenboolean否指定是否应更新隐藏的角色分配。

响应示例

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "User roles have been updated."
}

状态码

状态码描述
200角色已分配。
403访问被拒绝。
404角色未找到。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

创建和移除团队角色分配

列出分配给团队的角色

GET /api/access-control/teams/:teamId/roles

列出直接分配给给定团队的角色。

查询参数

  • includeHidden：可选。设为 true 以包含 隐藏 的角色。

所需权限

操作范围
teams.roles:readteams:id:<团队 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
    }
]

状态码

状态码描述
200返回分配的角色集合。
403访问被拒绝。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

添加团队角色分配

POST /api/access-control/teams/:teamId/roles

将角色分配给指定团队。

对于批量更新，请考虑设置团队角色分配。

所需权限

permissions:type:delegate 范围确保用户只能分配具有其自身权限相同或子集的角色。例如，如果用户没有创建用户所需的权限，他们将无法分配包含这些权限的角色。这样做是为了防止权限升级。

操作范围
teams.roles:addpermissions:type:delegate

请求示例

http 
POST /api/access-control/teams/1/roles
Accept: application/json
Content-Type: application/json

{
    "roleUid": "XvHQJq57z"
}

JSON 请求体 schema

字段名称数据类型必需描述
roleUidstring是角色的 UID。

响应示例

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role added to the team."
}

状态码

状态码描述
200角色已分配给团队。
403访问被拒绝。
404角色未找到。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

移除团队角色分配

DELETE /api/access-control/teams/:teams/roles/:roleUID

从团队收回（移除）角色。

对于批量更新，请考虑设置团队角色分配。

所需权限

permissions:type:delegate 范围确保用户只能取消分配具有其自身权限相同或子集的角色。例如，如果用户没有创建用户所需的权限，他们将无法分配包含这些权限的角色。这样做是为了防止权限升级。```

操作范围
teams.roles:removepermissions: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."
}

状态码

状态码描述
200角色已取消分配。
403访问被拒绝。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

设置团队角色分配

PUT /api/access-control/teams/:teamId/roles

更新团队的角色分配，使其与提供的 UID 集合匹配。这将移除请求中未包含的已分配角色，并添加集合中但尚未分配给用户的角色。

如果您想添加或移除单个角色，请考虑使用添加团队角色分配或移除团队角色分配。

所需权限

permissions:type:delegate 范围确保用户只能分配或取消分配具有其自身权限相同或子集的角色。例如，如果用户没有创建用户所需的权限，他们将无法向团队分配或取消分配允许执行此操作的角色。这样做是为了防止权限升级。

操作范围
teams.roles:addpermissions:type:delegate
teams.roles:removepermissions:type:delegate

请求示例

http 
PUT /api/access-control/teams/1/roles
Accept: application/json
Content-Type: application/json

{
    "roleUids": [
        "ZiHQJq5nk",
        "GzNQ1357k"
    ]
}

JSON 请求体 schema

字段名称数据类型必需描述
roleUidslist是角色 UID 列表。
includeHiddenboolean否指定是否应更新隐藏的角色分配。

响应示例

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Team roles have been updated."
}

状态码

状态码描述
200角色已分配。
403访问被拒绝。
404角色未找到。
500发生意外错误。有关详细信息，请参阅响应体和/或服务器日志。

将基本角色重置为默认值

POST /api/access-control/roles/hard-reset

permissions:type:escalate 范围允许用户重置基本角色权限。这可能导致基本角色的权限超出调用者的权限范围。

将基本角色权限重置为默认值。

所需权限

操作范围
roles:writepermissions:type:escalate

请求示例

http 
POST /api/access-control/roles/hard-reset
Accept: application/json
Content-Type: application/json

{
    "BasicRoles": true
}

JSON 请求体 schema

字段名称数据类型必需描述
BasicRolesboolean否重置基本角色权限的选项。

响应示例

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Reset performed"
}

状态码

状态码描述
200已执行重置
500未能重置基本角色