M2M 组织成员管理 API

本文档描述第三方 M2M 应用在组织上下文中可调用的成员管理接口。

这组接口适用于：

• 按组织查询成员
• 按手机号创建或复用用户并加入组织
• 移除普通成员
• 查询成员在当前组织下的角色
• 替换成员在当前组织下的角色

如果你还没有完成后台配置，请先阅读：

• M2M 组织成员管理接入指南
• M2M 组织成员管理配置指南

基本信息

Base URL

https://your-domain.com

接口前缀

/api/v1/m2m/organizations/{organizationId}/members

认证方式

所有接口都要求：

Authorization: Bearer <m2m_access_token>

并且该 Token 必须满足：

• token_type = "m2m"
• Claim 中包含 organization_id
• Claim 中的 organization_id 与路径中的 {organizationId} 完全一致
• scope 中包含以下任一项：
  • manage:organizations
  • all

响应格式

成功响应

{
  "code": 0,
  "result": {},
  "message": "success"
}

失败响应

{
  "code": 41305,
  "result": null,
  "message": "组织管理员不允许由第三方应用移除"
}

业务限制

• 用户是平台全局用户，不是组织私有用户
• 手机号是“创建或复用用户”的主判定键
• 第三方应用不能设置组织管理员
• 第三方应用不能取消组织管理员
• 第三方应用不能移除组织管理员
• 角色分配为“全量替换”，不是增量追加

---

查询组织成员列表

GET /api/v1/m2m/organizations/{organizationId}/members

分页查询当前组织下的成员。

路径参数

参数	类型	必填	说明
organizationId	string	是	组织 ID

查询参数

参数	类型	必填	默认值	说明
page	integer	否	1	页码
page_size	integer	否	20	每页条数
phone	string	否	-	按手机号精确筛选
name	string	否	-	按姓名模糊筛选
is_admin	boolean	否	-	按管理员标记筛选

请求示例

curl -X GET "https://your-domain.com/api/v1/m2m/organizations/BxBgwQhpjDmtMpsLojRuj/members?page=1&page_size=20&is_admin=false" \
  -H "Authorization: Bearer <m2m_access_token>"

成功响应

{
  "code": 0,
  "message": "success",
  "result": {
    "total": 2,
    "result": [
      {
        "id": "_J4OiutDpPy_zl0kqNC_x",
        "username": "alice",
        "primary_phone": "13800000001",
        "primary_email": "alice@example.com",
        "name": "Alice",
        "is_admin": false,
        "joined_at": "2026-03-12T10:00:00Z",
        "created_at": "2026-03-12T10:00:00Z"
      }
    ],
    "page": 1,
    "page_size": 20
  }
}

返回字段

字段	类型	说明
id	string	平台用户 ID
username	string | null	用户名
primary_phone	string | null	用户主手机号
primary_email	string | null	用户主邮箱
name	string | null	用户姓名
is_admin	boolean	是否为组织管理员
joined_at	string	用户加入当前组织的时间
created_at	string	用户创建时间

可能错误

错误码	HTTP 状态	说明
41000	404	组织不存在
41300	500	获取组织成员列表失败

---

按手机号创建或加入组织成员

POST /api/v1/m2m/organizations/{organizationId}/members

按手机号创建平台用户，或将已有平台用户加入当前组织。

路径参数

参数	类型	必填	说明
organizationId	string	是	组织 ID

请求体

字段	类型	必填	说明
phone	string	是	用户手机号，主判定键
name	string	否	用户姓名
email	string	否	用户邮箱

请求示例

curl -X POST "https://your-domain.com/api/v1/m2m/organizations/BxBgwQhpjDmtMpsLojRuj/members" \
  -H "Authorization: Bearer <m2m_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "13800000002",
    "name": "Bob",
    "email": "bob@example.com"
  }'

行为说明

• 手机号不存在：创建新用户并加入组织
• 手机号已存在：复用已有用户并加入组织
• 用户已在该组织中：返回成功，不报重复错误

成功响应

{
  "code": 0,
  "message": "success",
  "result": {
    "id": "user_bob_xxx",
    "username": "bob",
    "primary_phone": "13800000002",
    "primary_email": "bob@example.com",
    "name": "Bob",
    "is_admin": false,
    "joined_at": "2026-03-12T10:02:00Z",
    "created_at": "2026-03-12T10:02:00Z"
  }
}

可能错误

错误码	HTTP 状态	说明
41000	404	组织不存在
41302	500	创建或加入组织成员失败

---

移除组织成员

DELETE /api/v1/m2m/organizations/{organizationId}/members/{userId}

从当前组织中移除一个普通成员，同时清除该成员在本组织下的角色分配。

路径参数

参数	类型	必填	说明
organizationId	string	是	组织 ID
userId	string	是	用户 ID

请求示例

curl -X DELETE "https://your-domain.com/api/v1/m2m/organizations/BxBgwQhpjDmtMpsLojRuj/members/user_bob_xxx" \
  -H "Authorization: Bearer <m2m_access_token>"

成功响应

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

业务限制

• 不能移除组织管理员
• 不会删除平台用户本身
• 只会删除该用户与当前组织的关系

可能错误

错误码	HTTP 状态	说明
41301	404	组织成员不存在
41303	500	移除组织成员失败
41305	403	组织管理员不允许由第三方应用移除

---

查询成员在当前组织下的角色

GET /api/v1/m2m/organizations/{organizationId}/members/{userId}/roles

获取某个成员在当前组织中的角色列表。

路径参数

参数	类型	必填	说明
organizationId	string	是	组织 ID
userId	string	是	用户 ID

请求示例

curl -X GET "https://your-domain.com/api/v1/m2m/organizations/BxBgwQhpjDmtMpsLojRuj/members/user_bob_xxx/roles" \
  -H "Authorization: Bearer <m2m_access_token>"

成功响应

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "id": "role_member_manager",
      "name": "member-manager",
      "description": "Can manage organization members",
      "type": "User",
      "created_at": "2026-03-01T08:00:00Z"
    }
  ]
}

可能错误

错误码	HTTP 状态	说明
41301	404	组织成员不存在
41304	500	获取或分配组织成员角色失败

---

替换成员在当前组织下的角色

PUT /api/v1/m2m/organizations/{organizationId}/members/{userId}/roles

全量替换成员在当前组织中的角色列表。

路径参数

参数	类型	必填	说明
organizationId	string	是	组织 ID
userId	string	是	用户 ID

请求体

字段	类型	必填	说明
role_ids	string[]	是	组织角色 ID 列表

请求示例

curl -X PUT "https://your-domain.com/api/v1/m2m/organizations/BxBgwQhpjDmtMpsLojRuj/members/user_bob_xxx/roles" \
  -H "Authorization: Bearer <m2m_access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role_ids": ["role_member_manager", "role_viewer"]
  }'

成功响应

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

行为说明

• 这是全量替换，不是追加
• 不影响用户在其他组织中的角色

可能错误

错误码	HTTP 状态	说明
41301	404	组织成员不存在
41304	500	分配组织成员角色失败

---

鉴权相关错误

这部分错误通常发生在接口层或中间件层，不一定带业务错误码。

HTTP 状态	消息	说明
401	缺少认证信息	未携带 Bearer Token
401	认证格式错误	Authorization 头格式错误
401	认证已过期或无效	Token 无效或已过期
403	仅支持机器对机器应用访问	当前 Token 不是 M2M Token
403	组织上下文不匹配	Token 中的 organization_id 与路径不一致
403	权限不足	Token scope 不包含 manage:organizations 或 all

推荐排查顺序

当第三方接入失败时，建议按以下顺序检查：

1. 应用是否为 MachineToMachine
2. 应用是否已绑定到目标组织
3. 该组织内的应用是否已分配组织角色
4. 组织角色是否绑定了 manage:organizations 或 all
5. 请求 Token 时的 organization_id 是否正确
6. 调用 API 时 URL 中的 {organizationId} 是否与 Token 一致

相关文档

• M2M 认证指南
• M2M 组织级 Token
• M2M 组织成员管理接入指南
• M2M 组织成员管理配置指南