POST/api/v1/orgs/:orgId/roles创建组织角色

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
orgId	string	组织 ID

Body

Name	Data Type	Required	Description
name	string	Yes	角色名
description	string	No	角色描述
permissions	array	Yes	权限标识列表

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

{
  "name": "开发",
  "description": "研发团队成员",
  "permissions": [
    "repo:read",
    "repo:write",
    "ci:trigger"
  ]
}

Response

Body

RoleDTO

Name	Data Type	Required	Description
roleId	string	Yes	角色 ID
name	string	Yes	角色名
description	string	No	角色描述
permissions	array	Yes	权限标识列表，如 team:manage
createdAt	string	Yes	创建时间

type RoleDTO = {
  /** 角色 ID */
  roleId: string
  /** 角色名 */
  name: string
  /** 角色描述 */
  description?: string
  /** 权限标识列表，如 team:manage */
  permissions: string[]
  /** 创建时间 */
  createdAt: string
}

{
  "roleId": "01JD8SRR3N6V0X8ZS7X1ZFN4A9M",
  "name": "开发",
  "description": "研发团队成员",
  "permissions": [
    "repo:read",
    "repo:write",
    "ci:trigger"
  ],
  "createdAt": "2026-09-03T07:00:00Z"
}

HTTP Code

HTTP Status	Meaning	Notes
200	成功	返回新角色
400	权限标识无效	含权限目录中不存在的标识
403	无权操作	需要组织管理权限
409	角色已存在	同名角色已存在

Response Code

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

code	Meaning	Notes
0	成功	返回新角色
2501	无权操作组织	当前用户不持有组织管理权限
2601	角色名已存在	同名角色已存在
2602	权限标识无效	含权限目录中不存在的标识

Examples

POST /api/v1/orgs/01JD8SRP1N4T8W6XQ5V9XDL2Y7K/roles
Authorization: Bearer st_7c1f9e05b28d4a63
Content-Type: application/json

{
  "name": "开发",
  "description": "研发团队成员",
  "permissions": ["repo:read", "repo:write", "ci:trigger"]
}

{
  "id": "01JD8SSBR6P0R8TM",
  "code": 0,
  "messages": [],
  "result": {
    "roleId": "01JD8SRR3N6V0X8ZS7X1ZFN4A9M",
    "name": "开发",
    "description": "研发团队成员",
    "permissions": ["repo:read", "repo:write", "ci:trigger"],
    "createdAt": "2026-09-03T07:00:00Z"
  }
}