成员 API

管理团队席位与角色——即共享你账户的颁发者、徽章和颁发记录的人员。

所有端点都需要身份验证。参见身份验证。每个请求都限定在已认证所有者的账户范围内。

可通过 API 分配的角色为 admin、editor 和 viewer。owner 角色保留给账户持有人，无法被分配或移除。

列出成员

获取你账户中的所有成员和待处理的邀请。

GET /members

示例

curl -X GET https://api.badges.ninja/members \
  -H "X-Api-Key: bws_your_api_key_here"

响应

{
  "items": [
    {
      "memberId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "email": "owner@acme.example.com",
      "role": "owner",
      "status": "active"
    },
    {
      "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "email": "editor@acme.example.com",
      "role": "editor",
      "status": "pending"
    }
  ]
}

对于已接受的成员，status 为 active；对于尚未接受的邀请，status 为 pending。

---

邀请成员

通过电子邮件邀请一个人加入账户。系统会向该地址发送一封带有接受链接的邀请邮件。

POST /members

参数

参数	类型	必填	说明
email	string	是	要邀请的电子邮件地址（必须是有效的邮箱）
role	string	是	要分配的角色——admin、editor、viewer 之一

示例

curl -X POST https://api.badges.ninja/members \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "email": "editor@acme.example.com",
      "role": "editor"
    }
  }'

响应

{
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "inviteId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "status": "pending"
}

错误

• 400 — role must be one of admin, editor, viewer
• 400 — 电子邮件地址无效或缺失
• 400 — seat limit reached — 该账户在其方案下没有空闲席位（Free：2，Starter：5，Pro：20，含所有者）。请移除一位成员或升级方案。
• 400 — 该邮箱已是本账户的成员或已有待处理的邀请

---

接受邀请

接受一个待处理的邀请。已认证用户的电子邮件必须与邀请发送到的地址一致。

POST /members/accept

参数

参数	类型	必填	说明
inviteId	string	是	接受链接邮件中的邀请 ID

示例

curl -X POST https://api.badges.ninja/members/accept \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "inviteId": "c3d4e5f6-a7b8-9012-cdef-123456789012"
    }
  }'

响应

{
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "status": "active"
}

错误

• 400 — email does not match invitation — 登录所用的电子邮件与被邀请的电子邮件不一致
• 404 — 邀请未找到（已接受、已取消，或 inviteId 有误）

---

更新成员角色

更改现有成员的角色。需要所有者或管理员权限。

POST /members/{memberId}/role

参数

参数	类型	必填	说明
memberId	string	是	成员 ID（路径参数）
role	string	是	新角色——admin、editor、viewer 之一

示例

curl -X POST https://api.badges.ninja/members/b2c3d4e5-f6a7-8901-bcde-f12345678901/role \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "role": "admin"
    }
  }'

响应

{
  "memberId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "role": "admin",
  "updated": true
}

错误

• 400 — role must be one of admin, editor, viewer
• 400 — the owner role cannot be changed
• 404 — 成员未找到

---

移除成员

将某成员从账户中移除，或取消一个待处理的邀请。该成员会立即失去访问权限，其席位随即释放。

DELETE /members/{memberId}

示例

curl -X DELETE https://api.badges.ninja/members/b2c3d4e5-f6a7-8901-bcde-f12345678901 \
  -H "X-Api-Key: bws_your_api_key_here"

响应

一个普通字符串：

"member has been removed"

错误

• 400 — the owner cannot be removed
• 404 — 成员未找到