POST/api/v1/admin/roles创建管理角色

Try it 面板需要启用 JavaScript。

创建 admin 范围角色并声明权限集合。

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

Body

Name	Data Type	Required	Description
name	string	Yes	角色名
description	string	No	角色描述
permissions	array	Yes	权限标识列表（admin: 前缀）

type RequestBody = {
  /** 角色名 */
  name: string
  /** 角色描述 */
  description?: string
  /** 权限标识列表（admin: 前缀） */
  permissions: string[]
}

{
  "name": "审计员",
  "description": "只读审计检索与导出",
  "permissions": [
    "admin:audit:read",
    "admin:audit:export"
  ]
}

Response

Body

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

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

{
  "roleId": "01JD8STK4N8V1Y9AT8X2AGN5B0R",
  "name": "审计员",
  "description": "只读审计检索与导出",
  "permissions": [
    "admin:audit:read",
    "admin:audit:export"
  ],
  "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	成功	返回新角色
2601	角色名已存在	同名角色已存在
2602	权限标识无效	含权限目录中不存在的标识

Examples

POST /api/v1/admin/roles
Authorization: Bearer st_7c1f9e05b28d4a63
Content-Type: application/json

{
  "name": "审计员",
  "description": "只读审计检索与导出",
  "permissions": ["admin:audit:read", "admin:audit:export"]
}

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