成员

组织成员是有权访问您的Capgo组织的用户。每个成员都有一个特定的角色,该角色决定了他们在组织内的权限。有效管理成员对于维护团队的安全和协作至关重要。

成员角色

常规角色

• read: 可以查看资源但不能进行更改
• upload: 可以上传新捆绑包并查看资源
• write: 可以修改资源并上传捆绑包
• admin: 可以管理组织设置和成员
• super_admin: 对组织拥有完全控制权

邀请角色

• invite_read: 待处理的读取访问邀请
• invite_upload: 待处理的上传访问邀请
• invite_write: 待处理的写入访问邀请
• invite_admin: 待处理的管理员访问邀请
• invite_super_admin: 待处理的超级管理员访问邀请

最佳实践

1. 角色分配: 分配角色时遵循最小权限原则
2. 定期审计: 定期审查成员访问权限并删除未使用的账户
3. 入职培训: 制定清晰的流程来添加新成员和分配角色
4. 离职处理: 及时删除离开组织的成员的访问权限

端点

POST

https://api.capgo.app/organization/members/

向组织添加新成员或更新现有成员的角色。请注意,您只能邀请已经拥有Capgo账户的用户 - 电子邮件必须对应现有的Capgo用户。

请求体

interface MemberCreate {
  orgId: string
  email: string
  role: "read" | "upload" | "write" | "admin" | "super_admin"
}

请求示例

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "org_123",
    "email": "newmember@example.com",
    "role": "write"
  }' \
  https://api.capgo.app/organization/members/

成功响应

{
  "status": "OK",
  "data": {
    "uid": "user_789",
    "email": "newmember@example.com",
    "role": "invite_write",
    "image_url": null
  }
}

注意事项:

• 添加新成员时,他们将收到邀请电子邮件。在接受邀请之前,其角色将以”invite_“为前缀。
• 用户必须在被邀请之前已经拥有Capgo账户。如果他们没有账户,应首先在 https://console.capgo.app/register/ 创建一个账户

GET

https://api.capgo.app/organization/members/

检索组织的所有成员。

查询参数

interface MemberQuery {
  orgId: string
}

响应类型

interface Member {
  uid: string;
  email: string;
  image_url: string;
  role: "invite_read" | "invite_upload" | "invite_write" | "invite_admin" | "invite_super_admin" | "read" | "upload" | "write" | "admin" | "super_admin";
}

请求示例

curl -H "authorization: your-api-key" \
  "https://api.capgo.app/organization/members/?orgId=org_123"

响应示例

{
  "data": [
    {
      "uid": "user_123",
      "email": "john@example.com",
      "image_url": "https://example.com/avatar.png",
      "role": "admin"
    },
    {
      "uid": "user_456",
      "email": "jane@example.com",
      "image_url": "https://example.com/avatar2.png",
      "role": "write"
    },
    {
      "uid": "user_789",
      "email": "bob@example.com",
      "image_url": null,
      "role": "invite_read"
    }
  ]
}

DELETE

https://api.capgo.app/organization/members/

从组织中删除成员。这将立即撤销其访问权限。

请求体

interface MemberDelete {
  orgId: string
  email: string
}

请求示例

curl -X DELETE \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "org_123",
    "email": "user@example.com"
  }' \
  https://api.capgo.app/organization/members/

成功响应

{
  "status": "OK"
}

错误处理

常见错误场景及其响应:

// 未找到成员
{
  "error": "Member not found",
  "status": "KO"
}

// 无效的角色
{
  "error": "Invalid role specified",
  "status": "KO"
}

// 权限被拒绝
{
  "error": "Insufficient permissions to manage members",
  "status": "KO"
}

// 无法删除最后一个管理员
{
  "error": "Cannot remove the last admin from the organization",
  "status": "KO"
}

// 无效的电子邮件
{
  "error": "Invalid email format",
  "status": "KO"
}

// 成员已存在
{
  "error": "Member already exists in organization",
  "status": "KO"
}

常见用例

1. 团队扩展: 添加具有适当角色的新团队成员
2. 访问控制: 随着职责变化管理成员权限
3. 安全审计: 定期审查成员列表和角色
4. 团队重组: 在组织变更期间更新角色