跳转到主要内容
POST
创建或更新角色

限制说明

使用说明

  • 省略 role_id(或置为 0)表示创建角色,总是分配新的 ID。传入本账户自定义角色的 ID 表示更新;其他 ID 返回 400 InvalidParameter(no role found by id),内置角色 ID(2、6、8)返回 400 InvalidParameter(Preset roles cannot be modified.)。
  • role_name 在账户内必须唯一,也不能与内置名称 Admin、Responder、Viewer 重复;冲突时返回 400。
  • 更新会同时覆盖 role_name、description、permission_ids:不传 description 会清空描述,不传 permission_ids 会移除该角色的全部权限。
  • 更新已禁用的角色不会改变其状态,角色仍为禁用;如需启用请调用 POST /role/enable。
  • permission_ids 中的每个 ID 都必须是 POST /role/permission/list(with_all: true)返回的权限,否则返回 400,不做任何修改。
  • 每次调用都会记录到账户审计日志,请不要把敏感信息放在请求字段中。

授权

app_key
string
query
必填

在 Flashduty 控制台 我的 → APP Key 中创建的 APP Key。可通过 query 参数 app_key 或请求头 Fd-App-Key 传入。实际可访问范围是该 APP Key 的权限范围与创建者当前角色权限的交集,请妥善保管。

请求体

application/json

创建或更新自定义角色的参数。

role_name
string
必填

角色显示名称,1–39 个字符。

Required string length: 1 - 39
role_id
integer<uint64>

要更新的自定义角色 ID。省略或置为 0 表示创建新角色。不要传内置角色 ID 2、6、8。

description
string

角色描述,最多 499 个字符。更新时不传会清空原有描述。

Maximum string length: 499
permission_ids
integer<uint64>[]

角色授予的权限 ID(取自 POST /role/permission/list)。整体替换原有权限;不传或传空数组会使角色没有任何权限。

响应

成功

成功响应结构。2xx 响应中 request_id 标识本次调用(同时出现在 Flashcat-Request-Id 响应头中),data 为接口业务 payload。失败响应使用不同结构,参见 ErrorResponse。

request_id
string
必填

本次请求的唯一 ID,也会在 Flashcat-Request-Id 响应头中返回。反馈问题时请一并附上。

示例:

"01HK8XQE3Z7JM2NTFQ5YJ8P9R4"

data
object

角色创建/更新结果。