成员 API - Qoder CN

组织成员的查询、角色更新、统计、配额与管理接口。

列出成员

GET /v1/organizations/{org_id}/members

查询参数：

参数	类型	说明
`userId`	string	按用户 UUID 精确匹配，不能与 `email` 同时使用
`email`	string	按邮箱精准查询
`includeDeleted`	boolean	是否包含已删除成员，默认 `false`
`maxResults`	integer	每页条目数，默认 20，最大 100
`nextToken`	string	分页游标

userId 必须是非空的标准 UUID。按 userId 或 email 精确匹配时，最多返回一个成员且不返回新的 nextToken；没有匹配成员时返回 200 OK 和空 members 数组。请求示例：

curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/members?maxResults=10" \
  -H "Authorization: Bearer <api_key>"

响应示例：

{
  "members": [
    {
      "id": "member_001",
      "userId": "550e8400-e29b-41d4-a716-446655440000",
      "email": "user@example.com",
      "name": "张三",
      "role": "org_member",
      "status": "ENABLED",
      "joinedAt": "2025-01-10T08:00:00Z"
    }
  ],
  "maxResults": 10,
  "nextToken": "token_abc"
}

成员状态值

状态	说明
`ENABLED`	已启用
`DISABLED`	已禁用
`UNACTIVATED`	未激活
`APPROVE_PENDING`	审批中
`APPROVE_DECLINED`	审批拒绝
`DELETED`	已删除

获取成员详情

GET /v1/organizations/{org_id}/members/{member_id}

请求示例：

curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/members/member_001" \
  -H "Authorization: Bearer <api_key>"

响应示例：

{
  "id": "member_001",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "name": "张三",
  "role": "org_member",
  "status": "ENABLED",
  "joinedAt": "2025-01-10T08:00:00Z"
}

创建成员

POST /v1/organizations/{org_id}/members

创建新用户并加入当前组织。该接口只创建新账号；邮箱已注册时不会复用已有账号，也不会修改已有账号的密码。请求体：

{
  "email": "user@example.com",
  "name": "张三",
  "password": "StrongPassword123!",
  "role": "org_member"
}

字段	类型	必填	说明
`email`	string	是	新用户邮箱，邮箱域名必须已在组织中验证并启用
`name`	string	是	用户和成员展示名
`password`	string	是	初始密码，必须满足密码强度要求且不会在响应中返回
`role`	string	否	`org_member` 或 `org_admin`，默认 `org_member`

请求示例：

curl -X POST "https://api.qoder.com.cn/v1/organizations/org_xxx/members" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","name":"张三","password":"StrongPassword123!","role":"org_member"}'

响应示例：

{
  "member": {
    "id": "member_001",
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "name": "张三",
    "role": "org_member",
    "status": "ENABLED",
    "joinedAt": "2026-05-23T08:00:00Z"
  }
}

可能返回 InvalidParameter、InvalidPassword、InvalidRole、EmailDomainRequired、EmailDomainNotSupported、InsufficientSeats（HTTP 400）或 EmailAlreadyExists（HTTP 409）。

成员统计

GET /v1/organizations/{org_id}/members/statistics

请求示例：

curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/members/statistics" \
  -H "Authorization: Bearer <api_key>"

响应示例：

{
  "totalMembers": 50,
  "billableMembers": 45,
  "adminMembers": 3,
  "purchasedSeats": 60,
  "remainingSeats": 15
}

字段	说明
`totalMembers`	成员总数
`billableMembers`	计费成员数
`adminMembers`	管理员数量
`purchasedSeats`	已购席位数
`remainingSeats`	剩余席位数

删除成员

DELETE /v1/organizations/{org_id}/members/{member_id}

请求示例：

curl -X DELETE "https://api.qoder.com.cn/v1/organizations/org_xxx/members/member_001" \
  -H "Authorization: Bearer <api_key>"

成功时返回 HTTP 204 No Content。

获取成员用量

GET /v1/organizations/{org_id}/members/{member_id}/quota

请求示例：

curl -X GET "https://api.qoder.com.cn/v1/organizations/org_xxx/members/member_001/quota" \
  -H "Authorization: Bearer <api_key>"

响应示例：

{
  "planQuota": 1000,
  "resourcePackageQuota": 500,
  "totalQuota": 1500,
  "sharedQuota": 200
}

字段	说明
`planQuota`	套餐配额
`resourcePackageQuota`	资源包配额
`totalQuota`	总配额
`sharedQuota`	共享配额

批量获取成员用量

POST /v1/organizations/{org_id}/members/batchGetQuota

请求体：

{
  "memberIds": ["member_001", "member_002", "member_003"]
}

memberIds：成员 ID 数组，支持 1–100 个。

请求示例：

curl -X POST "https://api.qoder.com.cn/v1/organizations/org_xxx/members/batchGetQuota" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"memberIds": ["member_001", "member_002"]}'

响应示例：

{
  "quotas": [
    {
      "memberId": "member_001",
      "planQuota": 1000,
      "resourcePackageQuota": 500,
      "totalQuota": 1500,
      "sharedQuota": 200
    },
    {
      "memberId": "member_002",
      "planQuota": 1000,
      "resourcePackageQuota": 0,
      "totalQuota": 1000,
      "sharedQuota": 200
    }
  ]
}

更新成员 Add-On Cap

PUT /v1/organizations/{org_id}/members/{member_id}/addon-cap

请求体：

{
  "addOnCap": 500
}

addOnCap 接受非负整数、null 或省略；null 或省略表示不限制，0 表示禁用。请求示例：

curl -X PUT "https://api.qoder.com.cn/v1/organizations/org_xxx/members/member_001/addon-cap" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"addOnCap": 500}'

响应示例：

{
  "memberId": "member_001",
  "email": "user@example.com",
  "addOnCap": 500
}

批量更新 Add-On Cap

POST /v1/organizations/{org_id}/batchUpdateAddOnCap

请求体：

{
  "addOnCap": 500,
  "memberIds": ["member_001", "member_002"]
}

单次请求支持 1～100 个非空成员 ID，所有成员设置为相同的额度上限。addOnCap 接受非负整数、null 或省略；null 或省略表示不限制。请求示例：

curl -X POST "https://api.qoder.com.cn/v1/organizations/org_xxx/batchUpdateAddOnCap" \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"addOnCap": 500, "memberIds": ["member_001", "member_002"]}'

响应示例：

{
  "members": [
    { "memberId": "member_001", "previousAddOnCap": 300 },
    { "memberId": "member_002" }
  ]
}

成员之前无限制时不返回 previousAddOnCap。请求校验可能返回 InvalidBatchAddOnCapRequest、EmptyMemberIDs、TooManyMemberIDs、EmptyMemberIDAtIndex 或 InvalidAddOnCapFormat。

更新成员角色

PUT /v1/organizations/{organization_id}/members/{member_id}/role 将组织成员的角色设置为组织管理员、组织成员、Config Admin 或 Directory。适用于 CN / Global、Teams / Enterprise，复用管理台使用的 IAM 角色变更能力。

认证与权限

使用目标组织的 API Key：Authorization: Bearer <api_key>。API Key 必须属于路径指定的组织；服务账号凭证不能调用此接口。member_id 必须属于该组织。

路径参数

参数	类型	必填	说明
`organization_id`	string	是	组织 ID
`member_id`	string	是	成员 ID，可通过成员查询接口获取，不是用户 ID

请求体

{
  "role": "org_admin"
}

字段	类型	必填	说明
`role`	string	是	`org_admin`：组织管理员；`org_member`：组织成员；`org_config_admin`：Config Admin；`org_directory`：Directory

role 不可省略、为 null 或为空字符串。不支持已废弃的 org_free_member 或其他角色。重复设置非计费角色时仍会执行 IAM 权益回收，可用于重试未完成的回收。

成功响应（200 OK）

直接返回更新后的成员详情，字段与获取成员详情接口一致。

{
  "id": "member_abc123",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Alice",
  "email": "alice@example.com",
  "role": "org_admin",
  "status": "ENABLED",
  "joinedAt": "2026-09-01T08:00:00Z"
}

业务限制

至少保留一名管理员（包括组织管理员和 Config Admin），具体角色切换限制与 Dashboard 共用 IAM 校验。
已移除的成员不能变更角色；其他不可用成员状态由 IAM 拒绝。
Teams 升级 Enterprise 待生效期间禁止变更角色。
Config Admin 和 Directory 的新分配要求组织已开启 DirectoryRole 灰度，未开启时返回 403。两者为非计费角色，切换后沿用 IAM 释放席位、清理计费权益及撤销会话的流程；转回计费角色需有可用席位，失败时沿用 IAM 补偿流程。特殊账号限制与 Dashboard 一致。

错误响应

错误码	HTTP 状态码	说明
`BadRequest`	400	请求体格式错误、成员 ID 无效或成员状态不允许变更
`InvalidRole`	400	角色缺失或不在允许范围内
`OrgMemberAdminCountLacked`	400	不能移除最后一名管理员角色
`OrganizationPendingUpgrade`	400	组织正在等待 Teams 升级 Enterprise 生效
`Unauthorized`	401	凭证缺失或无效
`Forbidden`	403	凭证无权限，或目标新角色未开启组织灰度
`UserNotTeamMember`	404	成员不存在、已移除或不属于该组织
`InternalError`	500	服务内部错误

其他 IAM 业务错误沿用标准 OpenAPI 错误响应，包含 requestId、code、message。

{
  "requestId": "req_abc123",
  "code": "InvalidRole",
  "message": "role must be org_admin, org_member, org_config_admin or org_directory"
}

调用示例

curl -X PUT 'https://api.qoder.com.cn/v1/organizations/org_xxx/members/member_abc123/role' \
  -H 'Authorization: Bearer <api_key>' \
  -H 'Content-Type: application/json' \
  -d '{"role":"org_member"}'

​列出成员

​成员状态值

​获取成员详情

​创建成员

​成员统计

​删除成员

​获取成员用量

​批量获取成员用量

​更新成员 Add-On Cap

​批量更新 Add-On Cap

​更新成员角色

​认证与权限

​路径参数

​请求体

​成功响应（200 OK）

​业务限制

​错误响应

​调用示例

列出成员

成员状态值

获取成员详情

创建成员

成员统计

删除成员

获取成员用量

批量获取成员用量

更新成员 Add-On Cap

批量更新 Add-On Cap

更新成员角色

认证与权限

路径参数

请求体

成功响应（200 OK）

业务限制

错误响应

调用示例