Members API

Quản lý ghế nhóm và vai trò — những người chia sẻ các nhà phát hành, huy hiệu và lượt trao của tài khoản bạn.

Tất cả điểm cuối đều yêu cầu xác thực. Xem Xác thực. Mọi yêu cầu đều được giới hạn trong phạm vi tài khoản của chủ sở hữu đã xác thực.

Các vai trò có thể được gán qua API là admin, editor và viewer. Vai trò owner được dành riêng cho người nắm giữ tài khoản và không thể được gán hay xóa.

Liệt Kê Thành Viên

Truy xuất tất cả thành viên và lời mời đang chờ trên tài khoản của bạn.

GET /members

Ví dụ

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

Phản hồi

{
  "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 là active đối với thành viên đã chấp nhận, hoặc pending đối với lời mời chưa được chấp nhận.

---

Mời Thành Viên

Mời một người vào tài khoản bằng email. Một email lời mời có liên kết chấp nhận sẽ được gửi đến địa chỉ đó.

POST /members

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
email	string	Có	Địa chỉ email để mời (phải là email hợp lệ)
role	string	Có	Vai trò để gán — một trong admin, editor, viewer

Ví dụ

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"
    }
  }'

Phản hồi

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

Lỗi

• 400 — role must be one of admin, editor, viewer
• 400 — địa chỉ email không hợp lệ hoặc bị thiếu
• 400 — seat limit reached — tài khoản không còn ghế trống cho gói (Miễn phí: 2, Starter: 5, Pro: 20, bao gồm cả chủ sở hữu). Hãy xóa một thành viên hoặc nâng cấp gói.
• 400 — email đã là thành viên hoặc đã có lời mời đang chờ trên tài khoản này

---

Chấp Nhận Lời Mời

Chấp nhận một lời mời đang chờ. Email của người dùng đã xác thực phải khớp với địa chỉ mà lời mời được gửi đến.

POST /members/accept

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
inviteId	string	Có	ID lời mời từ email liên kết chấp nhận

Ví dụ

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"
    }
  }'

Phản hồi

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

Lỗi

• 400 — email does not match invitation — email đã đăng nhập khác với email được mời
• 404 — không tìm thấy lời mời (đã được chấp nhận, đã hủy, hoặc inviteId sai)

---

Cập Nhật Vai Trò Thành Viên

Thay đổi vai trò của một thành viên hiện có. Yêu cầu quyền chủ sở hữu hoặc quản trị viên.

POST /members/{memberId}/role

Tham số

Tham số	Kiểu	Bắt buộc	Mô tả
memberId	string	Có	ID thành viên (tham số đường dẫn)
role	string	Có	Vai trò mới — một trong admin, editor, viewer

Ví dụ

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"
    }
  }'

Phản hồi

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

Lỗi

• 400 — role must be one of admin, editor, viewer
• 400 — the owner role cannot be changed
• 404 — không tìm thấy thành viên

---

Xóa Thành Viên

Xóa một thành viên khỏi tài khoản, hoặc hủy một lời mời đang chờ. Thành viên ngay lập tức mất quyền truy cập và ghế của họ được giải phóng.

DELETE /members/{memberId}

Ví dụ

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

Phản hồi

Một chuỗi đơn thuần:

"member has been removed"

Lỗi

• 400 — the owner cannot be removed
• 404 — không tìm thấy thành viên