组织配置

本文档说明如何创建组织、配置角色模板和权限模板，以及如何将权限分配给角色。

配置流程概览

搭建组织体系的推荐步骤：

1. 创建权限模板  ──>  2. 创建角色模板  ──>  3. 为角色分配权限  ──>  4. 创建组织  ──>  5. 添加成员并分配角色

其中步骤 1-3 属于"模板配置"（租户级，一次配置全局生效），步骤 4-5 属于"组织管理"（每个组织独立操作）。

创建组织

接口说明

方法	路径	说明
GET	/api/v1/organizations	获取组织列表
POST	/api/v1/organizations	创建组织
GET	/api/v1/organizations/:id	获取组织详情
PATCH	/api/v1/organizations/:id	更新组织
DELETE	/api/v1/organizations/:id	删除组织

创建组织

请求

POST /api/v1/organizations
Content-Type: application/json

请求体

字段	类型	必填	说明
name	string	是	组织名称，最长 128 字符
description	string	否	组织描述，最长 256 字符

请求示例

json

{
  "name": "Code Bird Technology",
  "description": "Core engineering team"
}

响应示例

json

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "org_abc123def456ghi78",
    "name": "Code Bird Technology",
    "description": "Core engineering team",
    "member_count": 0,
    "created_at": "2026-02-13T10:00:00Z"
  }
}

获取组织列表

请求

GET /api/v1/organizations?page=1&page_size=20

查询参数

参数	类型	必填	说明
page	integer	否	页码，默认 1
page_size	integer	否	每页数量，默认 20

响应示例

json

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [
      {
        "id": "org_abc123def456ghi78",
        "name": "Code Bird Technology",
        "description": "Core engineering team",
        "member_count": 15,
        "created_at": "2026-01-15T00:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "page_size": 20
  }
}

更新组织

请求

PATCH /api/v1/organizations/:id
Content-Type: application/json

请求体（所有字段均为可选）

字段	类型	说明
name	string	组织名称
description	string	组织描述

删除组织

请求

DELETE /api/v1/organizations/:id

删除组织时将级联清除：

该组织下的所有成员关系（organization_users）
该组织下的所有成员角色分配（organization_user_roles）

用户本身不会被删除。

配置权限模板

权限模板在租户级别定义，所有组织共享。建议使用 动作:资源 格式命名。

接口说明

方法	路径	说明
GET	/api/v1/organization-permissions	获取权限模板列表
POST	/api/v1/organization-permissions	创建权限模板
DELETE	/api/v1/organization-permissions/:id	删除权限模板

创建权限模板

请求

POST /api/v1/organization-permissions
Content-Type: application/json

请求体

字段	类型	必填	说明
name	string	是	权限名称，最长 128 字符
description	string	否	权限描述

请求示例

json

{
  "name": "read:members",
  "description": "View organization member list"
}

响应示例

json

{
  "code": 0,
  "message": "success",
  "data": {
    "id": "perm_abc123def456ghi7",
    "name": "read:members",
    "description": "View organization member list",
    "created_at": "2026-02-13T10:00:00Z"
  }
}

获取权限模板列表

请求

GET /api/v1/organization-permissions?page=1&page_size=50

删除权限模板

请求

DELETE /api/v1/organization-permissions/:id

注意：删除权限模板时，相关的角色-权限关联将被自动清除。已分配该权限的角色将失去对应能力。

配置角色模板

角色模板同样在租户级别定义，所有组织共享。

接口说明

方法	路径	说明
GET	/api/v1/organization-roles	获取角色模板列表
POST	/api/v1/organization-roles	创建角色模板
GET	/api/v1/organization-roles/:id	获取角色模板详情
PATCH	/api/v1/organization-roles/:id	更新角色模板
DELETE	/api/v1/organization-roles/:id	删除角色模板
GET	/api/v1/organization-roles/:id/scopes	获取角色绑定的组织权限
PUT	/api/v1/organization-roles/:id/scopes	为角色绑定组织权限

创建角色模板

请求

POST /api/v1/organization-roles
Content-Type: application/json

请求体

字段	类型	必填	说明
name	string	是	角色名称，最长 128 字符
description	string	否	角色描述

请求示例

json

{
  "name": "admin",
  "description": "Organization administrator with full access"
}

为角色分配权限

将组织权限模板关联到角色模板。使用 PUT 语义，传入的权限列表将完全替换角色当前的所有权限。

请求

PUT /api/v1/organization-roles/:id/scopes
Content-Type: application/json

请求体

字段	类型	必填	说明
scope_ids	string[]	是	组织权限模板 ID 数组

请求示例

json

{
  "scope_ids": [
    "perm_abc123def456ghi7",
    "perm_def456ghi789jkl0",
    "perm_ghi789jkl012mno3"
  ]
}

响应示例

json

{
  "code": 0,
  "message": "success",
  "data": null
}

查看角色的权限列表

请求

GET /api/v1/organization-roles/:id/scopes

响应示例

json

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "id": "perm_abc123def456ghi7",
      "name": "read:members",
      "description": "View organization member list",
      "created_at": "2026-02-13T10:00:00Z"
    },
    {
      "id": "perm_def456ghi789jkl0",
      "name": "manage:members",
      "description": "Add or remove organization members",
      "created_at": "2026-02-13T10:00:00Z"
    }
  ]
}

典型配置工作流

以下是一个完整的组织体系搭建示例：

第一步：创建权限模板

bash

# 创建成员管理权限
curl -X POST /api/v1/organization-permissions \
  -d '{"name": "read:members", "description": "View member list"}'

curl -X POST /api/v1/organization-permissions \
  -d '{"name": "manage:members", "description": "Add/remove members"}'

# 创建数据权限
curl -X POST /api/v1/organization-permissions \
  -d '{"name": "read:data", "description": "Read organization data"}'

curl -X POST /api/v1/organization-permissions \
  -d '{"name": "write:data", "description": "Write organization data"}'

# 创建设置权限
curl -X POST /api/v1/organization-permissions \
  -d '{"name": "manage:settings", "description": "Manage org settings"}'

第二步：创建角色模板

bash

# 管理员角色
curl -X POST /api/v1/organization-roles \
  -d '{"name": "admin", "description": "Full access administrator"}'

# 普通成员角色
curl -X POST /api/v1/organization-roles \
  -d '{"name": "member", "description": "Regular member"}'

# 只读观察者角色
curl -X POST /api/v1/organization-roles \
  -d '{"name": "viewer", "description": "Read-only viewer"}'

第三步：为角色分配权限

bash

# admin 角色 -> 全部权限
curl -X PUT /api/v1/organization-roles/{admin_id}/scopes \
  -d '{"scope_ids": ["{read_members_id}", "{manage_members_id}", "{read_data_id}", "{write_data_id}", "{manage_settings_id}"]}'

# member 角色 -> 读写数据 + 查看成员
curl -X PUT /api/v1/organization-roles/{member_id}/scopes \
  -d '{"scope_ids": ["{read_members_id}", "{read_data_id}", "{write_data_id}"]}'

# viewer 角色 -> 仅读取数据
curl -X PUT /api/v1/organization-roles/{viewer_id}/scopes \
  -d '{"scope_ids": ["{read_data_id}"]}'

第四步：创建组织

bash

curl -X POST /api/v1/organizations \
  -d '{"name": "Engineering Team", "description": "Core engineering"}'

第五步：添加成员并分配角色

参阅成员管理了解成员添加和角色分配的详细操作。

为角色绑定 API 资源权限（可选）

除了组织权限模板，角色还可以绑定 API 资源权限（Resource Scope）。这在第三方应用需要在组织上下文中访问受保护 API 资源时使用。

接口说明

方法	路径	说明
GET	/api/v1/organization-roles/:id/resource-scopes	获取角色绑定的 API 资源权限
PUT	/api/v1/organization-roles/:id/resource-scopes	为角色绑定 API 资源权限
DELETE	/api/v1/organization-roles/:id/resource-scopes/:scopeId	移除角色的某个 API 资源权限

绑定 API 资源权限

PUT /api/v1/organization-roles/:id/resource-scopes
Content-Type: application/json

{
  "scope_ids": ["scope_abc123", "scope_def456"]
}

scope_ids 中的 ID 是系统中已创建的 API 资源权限（Scope）的 ID，可在 API 资源 页面查看。

两种权限的区别

维度	组织权限模板	API 资源权限
定义位置	授权 → 组织模板 → 权限模板	API 资源 → 资源详情 → Scope
绑定方式	`/organization-roles/:id/scopes`	`/organization-roles/:id/resource-scopes`
Token 中的位置	组织操作 Token 的 `scope` 字段	组织 API 资源 Token 的 `scope` 字段
获取方式	`refresh_token + organization_id`	`refresh_token + organization_id + resource`
适用场景	控制组织内部操作	控制组织上下文下的 API 访问

通过管理后台配置

除了使用 API，你也可以通过 Code Bird Cloud 管理后台的图形界面完成上述配置：

进入 授权 → 组织模板 页面
- 角色模板 Tab：创建、编辑角色模板，点击「管理权限」为角色绑定组织权限
- 权限模板 Tab：创建、删除组织权限模板
进入组织页面，创建和管理组织
点击组织详情，管理成员和成员角色分配

管理后台提供了更直观的操作方式，适合日常运维使用。

权限如何传递到 Token

配置完成后，权限通过 OIDC Token 传递给第三方应用。详细说明参见组织级 RBAC — 权限在 Token 中的体现和组织级登录。

组织配置 ​

配置流程概览 ​

创建组织 ​

接口说明 ​

创建组织 ​

获取组织列表 ​

更新组织 ​

删除组织 ​

配置权限模板 ​

接口说明 ​

创建权限模板 ​

获取权限模板列表 ​

删除权限模板 ​

配置角色模板 ​

接口说明 ​

创建角色模板 ​

为角色分配权限 ​

查看角色的权限列表 ​

典型配置工作流 ​

第一步：创建权限模板 ​

第二步：创建角色模板 ​

第三步：为角色分配权限 ​

第四步：创建组织 ​

第五步：添加成员并分配角色 ​

为角色绑定 API 资源权限（可选） ​

接口说明 ​

绑定 API 资源权限 ​

两种权限的区别 ​

通过管理后台配置 ​

权限如何传递到 Token ​

组织配置

配置流程概览

创建组织

接口说明

创建组织

获取组织列表

更新组织

删除组织

配置权限模板

接口说明

创建权限模板

获取权限模板列表

删除权限模板

配置角色模板

接口说明

创建角色模板

为角色分配权限

查看角色的权限列表

典型配置工作流

第一步：创建权限模板

第二步：创建角色模板

第三步：为角色分配权限

第四步：创建组织

第五步：添加成员并分配角色

为角色绑定 API 资源权限（可选）

接口说明

绑定 API 资源权限

两种权限的区别

通过管理后台配置

权限如何传递到 Token