成員 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 — 成員未找到