Members API

Gestisci le postazioni e i ruoli del team — le persone che condividono gli emittenti, i badge e le assegnazioni del tuo account.

Tutti gli endpoint richiedono l'autenticazione. Consulta Autenticazione. Ogni richiesta è delimitata all'account dell'owner autenticato.

I ruoli che possono essere assegnati tramite l'API sono admin, editor e viewer. Il ruolo owner è riservato al titolare dell'account e non può essere assegnato o rimosso.

Elenca i membri

Recupera tutti i membri e gli inviti in attesa del tuo account.

GET /members

Esempio

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

Risposta

{
  "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 per i membri che hanno accettato, oppure pending per gli inviti non ancora accettati.

---

Invita un membro

Invita una persona all'account tramite email. Un'email di invito con un link di accettazione viene inviata all'indirizzo.

POST /members

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
email	string	Sì	Indirizzo email da invitare (deve essere un'email valida)
role	string	Sì	Ruolo da assegnare — uno tra admin, editor, viewer

Esempio

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

Risposta

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

Errori

• 400 — role must be one of admin, editor, viewer
• 400 — indirizzo email non valido o mancante
• 400 — seat limit reached — l'account non ha postazioni libere per il piano (Free: 2, Starter: 5, Pro: 20, incluso l'owner). Rimuovi un membro o passa a un piano superiore.
• 400 — l'email è già un membro o ha un invito in attesa su questo account

---

Accetta un invito

Accetta un invito in attesa. L'email dell'utente autenticato deve corrispondere all'indirizzo a cui è stato inviato l'invito.

POST /members/accept

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
inviteId	string	Sì	L'ID dell'invito contenuto nell'email con il link di accettazione

Esempio

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

Risposta

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

Errori

• 400 — email does not match invitation — l'email con cui si è effettuato l'accesso è diversa dall'email invitata
• 404 — invito non trovato (già accettato, annullato oppure inviteId errato)

---

Aggiorna il ruolo di un membro

Cambia il ruolo di un membro esistente. Richiede privilegi di owner o admin.

POST /members/{memberId}/role

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
memberId	string	Sì	L'ID del membro (parametro di percorso)
role	string	Sì	Nuovo ruolo — uno tra admin, editor, viewer

Esempio

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

Risposta

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

Errori

• 400 — role must be one of admin, editor, viewer
• 400 — the owner role cannot be changed
• 404 — membro non trovato

---

Rimuovi un membro

Rimuovi un membro dall'account oppure annulla un invito in attesa. Il membro perde immediatamente l'accesso e la sua postazione si libera.

DELETE /members/{memberId}

Esempio

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

Risposta

Una semplice stringa:

"member has been removed"

Errori

• 400 — the owner cannot be removed
• 404 — membro non trovato