Members API

Urus kerusi pasukan dan peranan — orang yang berkongsi pengeluar, lencana dan kredensial akaun anda.

Semua titik akhir memerlukan pengesahan. Lihat Pengesahan. Setiap permintaan diskopkan kepada akaun owner yang disahkan.

Peranan yang boleh ditetapkan melalui API ialah admin, editor, dan viewer. Peranan owner dikhaskan untuk pemegang akaun dan tidak boleh ditetapkan atau dikeluarkan.

Senaraikan Ahli

Dapatkan semua ahli dan jemputan tertangguh pada akaun anda.

GET /members

Contoh

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

Respons

{
  "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 ialah active untuk ahli yang telah menerima, atau pending untuk jemputan yang belum diterima.

---

Jemput Ahli

Jemput seseorang ke akaun melalui e-mel. Satu e-mel jemputan dengan pautan terima dihantar ke alamat tersebut.

POST /members

Parameter

Parameter	Jenis	Diperlukan	Penerangan
email	string	Ya	Alamat e-mel untuk dijemput (mesti e-mel yang sah)
role	string	Ya	Peranan untuk ditetapkan — salah satu daripada admin, editor, viewer

Contoh

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

Respons

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

Ralat

• 400 — role must be one of admin, editor, viewer
• 400 — alamat e-mel tidak sah atau tiada
• 400 — seat limit reached — akaun tiada kerusi kosong untuk pelan (Free: 2, Starter: 5, Pro: 20, termasuk owner). Keluarkan seorang ahli atau naik taraf pelan.
• 400 — e-mel itu sudah menjadi ahli atau mempunyai jemputan tertangguh pada akaun ini

---

Terima Jemputan

Terima jemputan tertangguh. E-mel pengguna yang disahkan mesti sepadan dengan alamat yang jemputan itu dihantar kepadanya.

POST /members/accept

Parameter

Parameter	Jenis	Diperlukan	Penerangan
inviteId	string	Ya	ID jemputan daripada e-mel pautan terima

Contoh

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

Respons

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

Ralat

• 400 — email does not match invitation — e-mel yang dilog masuk berbeza daripada e-mel yang dijemput
• 404 — jemputan tidak ditemui (sudah diterima, dibatalkan, atau inviteId salah)

---

Kemas Kini Peranan Ahli

Tukar peranan ahli sedia ada. Memerlukan keistimewaan owner atau admin.

POST /members/{memberId}/role

Parameter

Parameter	Jenis	Diperlukan	Penerangan
memberId	string	Ya	ID ahli (parameter laluan)
role	string	Ya	Peranan baharu — salah satu daripada admin, editor, viewer

Contoh

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

Respons

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

Ralat

• 400 — role must be one of admin, editor, viewer
• 400 — the owner role cannot be changed
• 404 — ahli tidak ditemui

---

Keluarkan Ahli

Keluarkan seorang ahli daripada akaun, atau batalkan jemputan tertangguh. Ahli itu serta-merta kehilangan akses dan kerusi mereka dibebaskan.

DELETE /members/{memberId}

Contoh

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

Respons

Satu rentetan biasa:

"member has been removed"

Ralat

• 400 — the owner cannot be removed
• 404 — ahli tidak ditemui