API de miembros

Gestiona los asientos de equipo y los roles: las personas que comparten los emisores, insignias y otorgamientos de tu cuenta.

Todos los endpoints requieren autenticación. Consulta Autenticación. Cada solicitud se limita al alcance de la cuenta del propietario autenticado.

Los roles que se pueden asignar a través de la API son admin, editor y viewer. El rol owner está reservado para el titular de la cuenta y no se puede asignar ni eliminar.

Listar miembros

Recupera todos los miembros y las invitaciones pendientes de tu cuenta.

GET /members

Ejemplo

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

Respuesta

{
  "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 es active para los miembros que han aceptado, o pending para las invitaciones que aún no se han aceptado.

---

Invitar a un miembro

Invita a una persona a la cuenta mediante su correo electrónico. Se envía a la dirección un correo de invitación con un enlace de aceptación.

POST /members

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
email	string	Sí	Dirección de correo a invitar (debe ser un correo válido)
role	string	Sí	Rol a asignar — uno de admin, editor, viewer

Ejemplo

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

Respuesta

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

Errores

• 400 — role must be one of admin, editor, viewer
• 400 — dirección de correo inválida o ausente
• 400 — seat limit reached — la cuenta no tiene asientos libres para el plan (Free: 2, Starter: 5, Pro: 20, incluido el propietario). Elimina un miembro o mejora el plan.
• 400 — el correo ya es miembro o tiene una invitación pendiente en esta cuenta

---

Aceptar una invitación

Acepta una invitación pendiente. El correo del usuario autenticado debe coincidir con la dirección a la que se envió la invitación.

POST /members/accept

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
inviteId	string	Sí	El ID de invitación del correo con el enlace de aceptación

Ejemplo

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

Respuesta

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

Errores

• 400 — email does not match invitation — el correo con el que se inició sesión difiere del correo invitado
• 404 — invitación no encontrada (ya aceptada, cancelada, o el inviteId es incorrecto)

---

Actualizar el rol de un miembro

Cambia el rol de un miembro existente. Requiere privilegios de propietario o administrador.

POST /members/{memberId}/role

Parámetros

Parámetro	Tipo	Obligatorio	Descripción
memberId	string	Sí	El ID del miembro (parámetro de ruta)
role	string	Sí	Nuevo rol — uno de admin, editor, viewer

Ejemplo

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

Respuesta

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

Errores

• 400 — role must be one of admin, editor, viewer
• 400 — the owner role cannot be changed
• 404 — miembro no encontrado

---

Eliminar un miembro

Elimina un miembro de la cuenta o cancela una invitación pendiente. El miembro pierde el acceso de inmediato y su asiento queda libre.

DELETE /members/{memberId}

Ejemplo

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

Respuesta

Una cadena simple:

"member has been removed"

Errores

• 400 — the owner cannot be removed
• 404 — miembro no encontrado