Members API

Kelola kursi tim dan peran — orang-orang yang berbagi penerbit, lencana, dan pemberian akun Anda.

Semua endpoint memerlukan autentikasi. Lihat Autentikasi. Setiap permintaan dibatasi pada akun pemilik yang terautentikasi.

Peran yang dapat ditetapkan melalui API adalah admin, editor, dan viewer. Peran owner dicadangkan untuk pemegang akun dan tidak dapat ditetapkan atau dihapus.

Daftar Anggota

Ambil semua anggota dan undangan yang tertunda pada akun 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 bernilai active untuk anggota yang telah menerima, atau pending untuk undangan yang belum diterima.

---

Undang Anggota

Undang seseorang ke akun melalui email. Email undangan berisi tautan penerimaan dikirim ke alamat tersebut.

POST /members

Parameter

Parameter	Tipe	Wajib	Deskripsi
email	string	Ya	Alamat email yang akan diundang (harus berupa email yang valid)
role	string	Ya	Peran yang akan ditetapkan — salah satu dari 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"
}

Kesalahan

• 400 — role must be one of admin, editor, viewer
• 400 — alamat email tidak valid atau tidak ada
• 400 — seat limit reached — akun tidak memiliki kursi yang tersedia untuk paket tersebut (Gratis: 2, Starter: 5, Pro: 20, termasuk pemilik). Hapus seorang anggota atau tingkatkan paket.
• 400 — email sudah menjadi anggota atau memiliki undangan yang tertunda pada akun ini

---

Terima Undangan

Terima undangan yang tertunda. Email pengguna yang terautentikasi harus cocok dengan alamat tujuan undangan dikirim.

POST /members/accept

Parameter

Parameter	Tipe	Wajib	Deskripsi
inviteId	string	Ya	ID undangan dari email tautan penerimaan

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

Kesalahan

• 400 — email does not match invitation — email yang digunakan untuk masuk berbeda dengan email yang diundang
• 404 — undangan tidak ditemukan (sudah diterima, dibatalkan, atau inviteId salah)

---

Perbarui Peran Anggota

Ubah peran anggota yang sudah ada. Memerlukan hak istimewa pemilik atau admin.

POST /members/{memberId}/role

Parameter

Parameter	Tipe	Wajib	Deskripsi
memberId	string	Ya	ID anggota (parameter path)
role	string	Ya	Peran baru — salah satu dari 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
}

Kesalahan

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

---

Hapus Anggota

Hapus anggota dari akun, atau batalkan undangan yang tertunda. Anggota langsung kehilangan akses dan kursi 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

Sebuah string sederhana:

"member has been removed"

Kesalahan

• 400 — the owner cannot be removed
• 404 — anggota tidak ditemukan