Members-API

Verwalten Sie Team-Sitze und Rollen — die Personen, die sich die Aussteller, Badges und Nachweise Ihres Kontos teilen.

Alle Endpunkte erfordern eine Authentifizierung. Siehe Authentifizierung. Jede Anfrage ist auf das Konto des authentifizierten Owners beschränkt.

Rollen, die über die API zugewiesen werden können, sind admin, editor und viewer. Die Rolle owner ist dem Kontoinhaber vorbehalten und kann nicht zugewiesen oder entfernt werden.

Mitglieder auflisten

Rufen Sie alle Mitglieder und ausstehenden Einladungen Ihres Kontos ab.

GET /members

Beispiel

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

Antwort

{
  "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 ist active für Mitglieder, die die Einladung angenommen haben, oder pending für Einladungen, die noch nicht angenommen wurden.

---

Mitglied einladen

Laden Sie eine Person per E-Mail zum Konto ein. Eine Einladungs-E-Mail mit einem Annahme-Link wird an die Adresse gesendet.

POST /members

Parameter

Parameter	Typ	Erforderlich	Beschreibung
email	string	Ja	Einzuladende E-Mail-Adresse (muss eine gültige E-Mail sein)
role	string	Ja	Zuzuweisende Rolle — eine von admin, editor, viewer

Beispiel

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

Antwort

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

Fehler

• 400 — role must be one of admin, editor, viewer
• 400 — ungültige oder fehlende E-Mail-Adresse
• 400 — seat limit reached — das Konto hat keine freien Sitze für den Tarif (Free: 2, Starter: 5, Pro: 20, einschließlich des Owners). Entfernen Sie ein Mitglied oder wechseln Sie den Tarif.
• 400 — die E-Mail ist bereits Mitglied oder hat eine ausstehende Einladung für dieses Konto

---

Einladung annehmen

Nehmen Sie eine ausstehende Einladung an. Die E-Mail-Adresse des authentifizierten Benutzers muss mit der Adresse übereinstimmen, an die die Einladung gesendet wurde.

POST /members/accept

Parameter

Parameter	Typ	Erforderlich	Beschreibung
inviteId	string	Ja	Die Einladungs-ID aus der Annahme-Link-E-Mail

Beispiel

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

Antwort

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

Fehler

• 400 — email does not match invitation — die angemeldete E-Mail-Adresse unterscheidet sich von der eingeladenen E-Mail-Adresse
• 404 — Einladung nicht gefunden (bereits angenommen, storniert oder die inviteId ist falsch)

---

Mitgliedsrolle aktualisieren

Ändern Sie die Rolle eines bestehenden Mitglieds. Erfordert Owner- oder Admin-Rechte.

POST /members/{memberId}/role

Parameter

Parameter	Typ	Erforderlich	Beschreibung
memberId	string	Ja	Die Mitglieds-ID (Pfadparameter)
role	string	Ja	Neue Rolle — eine von admin, editor, viewer

Beispiel

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

Antwort

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

Fehler

• 400 — role must be one of admin, editor, viewer
• 400 — the owner role cannot be changed
• 404 — Mitglied nicht gefunden

---

Mitglied entfernen

Entfernen Sie ein Mitglied aus dem Konto oder stornieren Sie eine ausstehende Einladung. Das Mitglied verliert sofort den Zugriff und sein Sitz wird frei.

DELETE /members/{memberId}

Beispiel

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

Antwort

Ein reiner String:

"member has been removed"

Fehler

• 400 — the owner cannot be removed
• 404 — Mitglied nicht gefunden