PATCH/api/v1/admin/roles/:roleId更新管理角色

Try it 面板需要启用 JavaScript。

更新角色名称、描述与权限集合。

Request

Headers

Name	Data Type	Required	Description
Authorization	string	Yes	会话令牌认证，格式 `Bearer <sessionToken>`
Content-Type	string	Yes	请求体内容类型（默认值 "application/json"）

type RequestHeaders = {
  /** 会话令牌认证，格式 `Bearer <sessionToken>` */
  Authorization: string
  /** 请求体内容类型，默认值 "application/json" */
  Content-Type: string
}

{
  "Authorization": "Bearer st_7c1f9e05b28d4a63",
  "Content-Type": "application/json"
}

URL Parameters

Name	Data Type	Description
roleId	string	角色 ID

Body

Name	Data Type	Required	Description
name	string	No	角色名
description	string	No	角色描述
permissions	array	No	权限标识全集（整体替换）

type RequestBody = {
  /** 角色名 */
  name?: string
  /** 角色描述 */
  description?: string
  /** 权限标识全集（整体替换） */
  permissions?: string[]
}

{
  "permissions": [
    "admin:audit:read",
    "admin:audit:export",
    "admin:log:summary"
  ]
}

Response

Body

Name	Data Type	Required	Description
roleId	string	Yes	角色 ID
name	string	Yes	角色名
description	string	No	角色描述
permissions	array	Yes	权限标识列表
builtin	boolean	Yes	是否内置角色
createdAt	string	Yes	创建时间

type ResponseBody = {
  /** 角色 ID */
  roleId: string
  /** 角色名 */
  name: string
  /** 角色描述 */
  description?: string
  /** 权限标识列表 */
  permissions: string[]
  /** 是否内置角色 */
  builtin: boolean
  /** 创建时间 */
  createdAt: string
}

{
  "roleId": "01JD8STK4N8V1Y9AT8X2AGN5B0R",
  "name": "审计员",
  "description": "只读审计检索与导出",
  "permissions": [
    "admin:audit:read",
    "admin:audit:export",
    "admin:log:summary"
  ],
  "builtin": false,
  "createdAt": "2026-10-14T17:00:00Z"
}

HTTP Code

HTTP Status	Meaning	Notes
200	成功	返回更新后的角色
400	权限标识无效	含权限目录中不存在的标识
409	内置角色	内置角色的权限集合不可修改

Response Code

响应使用统一信封 {id, code, messages, result}，其 code 字段：

code	Meaning	Notes
0	成功	返回更新后的角色
2602	权限标识无效	含权限目录中不存在的标识
2604	内置角色不可修改	内置角色的权限集合不可修改

Examples

PATCH /api/v1/admin/roles/01JD8STK4N8V1Y9AT8X2AGN5B0R
Authorization: Bearer st_7c1f9e05b28d4a63
Content-Type: application/json

{
  "permissions": ["admin:audit:read", "admin:audit:export", "admin:log:summary"]
}

{
  "id": "01JD8STM6Q0X3CBC",
  "code": 0,
  "messages": [],
  "result": {
    "roleId": "01JD8STK4N8V1Y9AT8X2AGN5B0R",
    "name": "审计员",
    "description": "只读审计检索与导出",
    "permissions": ["admin:audit:read", "admin:audit:export", "admin:log:summary"],
    "builtin": false,
    "createdAt": "2026-10-14T17:00:00Z"
  }
}