Go M2M 组织成员管理 SDK

本教程介绍如何在 Go 服务端使用官方 codebird-go-sdk 的 M2MClient，通过 client_credentials 调用 Code Bird Cloud 的组织成员管理接口。

它适用于以下场景：

• 你的业务系统已经有自己的后台和权限模型
• 当前登录用户的权限判断由你的服务端完成
• 你的服务端需要再调用 Code Bird Cloud，管理某个组织下的成员

这条能力线是服务端管理调用，不适合让 SPA 直接持有。

这和 Go Verifier SDK 的区别

同一个 codebird-go-sdk 目前有两条能力线：

• Verifier
  • 验证前端带来的用户 access token
  • 读取用户和组织上下文
• M2MClient
  • 使用 client_credentials 获取 M2M token
  • 调用组织成员管理接口

推荐组合方式是：

1. 前端通过 React SDK 登录
2. 你的 Go 后端用 Verifier 验用户 token
3. 你的 Go 后端按业务规则判断“当前用户是否有权管理这个组织”
4. 通过后，再用 M2MClient 调组织成员管理接口

为什么不用 SPA 直接调这些接口

组织成员管理属于平台管理能力，主路径应放在服务端：

• 需要 client_secret
• 需要审计和权限前置判断
• 不适合让公开客户端直接持有高权限调用能力

因此推荐架构是：

SPA
  -> 你的业务后端
  -> 验当前登录用户 token
  -> 判断是否允许管理当前组织
  -> M2MClient
  -> Code Bird Cloud 组织成员管理接口

安装

go get github.com/lshaofan/codebird-go-sdk

最小配置

client, err := codebird.NewM2MClient(codebird.M2MConfig{
    Endpoint:       "https://auth.codebird.cloud",
    ClientID:       "YOUR_M2M_CLIENT_ID",
    ClientSecret:   "YOUR_M2M_CLIENT_SECRET",
    OrganizationID: "BxBgwQhpjDmtMpsLojRuj",
})

配置说明

• Endpoint：Code Bird Cloud 认证中心地址
• ClientID：M2M 应用的 Client ID
• ClientSecret：M2M 应用的 Client Secret
• OrganizationID：目标组织 ID，SDK 会用它申请组织级 token
• Resource：可选。只有在你明确要申请组织级 API resource token 时才传

当前 M2MClient 会在内部处理：

• client_credentials token 获取
• token 缓存
• token 到期前续期
• Authorization header 拼装

如果你的目标只是调用组织成员管理接口，推荐默认不传 Resource。 也就是说，当前标准接法是：

• client_credentials
• organization_id
• 不传 resource

最小调用示例

查询组织成员列表

members, err := client.ListOrganizationMembers(ctx, "BxBgwQhpjDmtMpsLojRuj", codebird.ListOrganizationMembersInput{
    Page:     1,
    PageSize: 20,
})
if err != nil {
    return err
}

for _, member := range members.Data {
    fmt.Println(member.ID, member.Name, member.PrimaryPhone, member.IsAdmin)
}

添加成员

member, err := client.AddOrganizationMember(ctx, "BxBgwQhpjDmtMpsLojRuj", codebird.AddOrganizationMemberInput{
    Phone: "13800000002",
    Name:  "Bob",
    Email: "bob@example.com",
})
if err != nil {
    return err
}

fmt.Println(member.ID)

移除成员

err := client.RemoveOrganizationMember(ctx, "BxBgwQhpjDmtMpsLojRuj", "user_bob_xxx")
if err != nil {
    return err
}

查询成员角色

roles, err := client.GetOrganizationMemberRoles(ctx, "BxBgwQhpjDmtMpsLojRuj", "user_bob_xxx")
if err != nil {
    return err
}

for _, role := range roles {
    fmt.Println(role.ID, role.Name)
}

更新成员角色

err := client.UpdateOrganizationMemberRoles(ctx, "BxBgwQhpjDmtMpsLojRuj", "user_bob_xxx", codebird.UpdateOrganizationMemberRolesInput{
    RoleIDs: []string{"role_a", "role_b"},
})
if err != nil {
    return err
}

当前正式支持的接口

当前版本先聚焦组织成员管理：

• ListOrganizationMembers
• AddOrganizationMember
• RemoveOrganizationMember
• GetOrganizationMemberRoles
• UpdateOrganizationMemberRoles

这里是刻意收边界的结果。当前版本还不承诺：

• 全量组织资料管理
• 全量用户资料管理
• 全量 Management API

AddOrganizationMember 当前字段范围

当前后端实际支持的新增成员字段为：

• phone
• name
• email

最小配置检查清单

在使用 Go SDK 联调前，请先确认：

• 应用类型为 MachineToMachine
• 应用已绑定到目标组织
• 该应用在目标组织内已分配组织角色
• 组织角色包含组织管理所需权限，如 manage:organizations 或 all
• 申请 token 时使用 organization_id
• 只做组织成员管理时，不要额外传 resource

因此 Go SDK 当前 AddOrganizationMemberInput 也只暴露这三个字段，不额外承诺 avatar、role_ids 等尚未稳定的参数。

推荐的服务端接法

更健康的接法不是“你的服务端一收到请求就直接调 M2M client”，而是：

1. 验当前登录用户 token
2. 判断当前用户是否有权管理这个组织
3. 通过后，再用 M2MClient 调平台接口

例如：

if !authCtx.HasOrganizationRole(organizationID, "admin") {
    http.Error(w, "forbidden", http.StatusForbidden)
    return
}

members, err := m2mClient.ListOrganizationMembers(r.Context(), organizationID, codebird.ListOrganizationMembersInput{
    Page:     1,
    PageSize: 20,
})

示例工程

仓库内已经提供了一个最小 CLI 示例，路径是：

• sdk/go/examples/m2m-organization-members

你可以直接用环境变量 + 命令行方式调用：

cd sdk/go
go run ./examples/m2m-organization-members list <organization-id>
go run ./examples/m2m-organization-members add <organization-id> <phone> [name] [email]
go run ./examples/m2m-organization-members remove <organization-id> <user-id>
go run ./examples/m2m-organization-members roles <organization-id> <user-id>
go run ./examples/m2m-organization-members update-roles <organization-id> <user-id> <role-id> [role-id...]

为什么当前仍然不做 Gin 官方适配

这个决定和 verifier 保持一致：

• SDK 核心应该保持框架无关
• Gin / Echo / Fiber 的上下文与错误约定并不统一
• 组织成员管理通常还要结合业务系统自己的权限判断、审计和日志

因此当前策略是：

• 官方提供通用 Verifier 和 M2MClient
• 官方提供示例和推荐范式
• 不提供 Gin 官方中间件或 controller 封装

相关文档

• Go Verifier SDK
• React SPA + Go 后端 SDK 配套接入
• M2M 组织成员管理接入指南
• M2M 组织成员管理 API