API de membros

Faça a gestão dos lugares de equipa e das funções — as pessoas que partilham os emissores, crachás e credenciais da sua conta.

Todos os endpoints exigem autenticação. Consulte Autenticação. Cada pedido está limitado ao âmbito da conta do proprietário autenticado.

As funções que podem ser atribuídas através da API são admin, editor e viewer. A função owner está reservada ao titular da conta e não pode ser atribuída nem removida.

Listar membros

Obtenha todos os membros e convites pendentes da sua conta.

GET /members

Exemplo

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

Resposta

{
  "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 para membros que aceitaram, ou pending para convites que ainda não foram aceites.

---

Convidar membro

Convide uma pessoa para a conta por e-mail. É enviado para o endereço um e-mail de convite com uma ligação de aceitação.

POST /members

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
email	string	Sim	Endereço de e-mail a convidar (deve ser um e-mail válido)
role	string	Sim	Função a atribuir — uma de admin, editor, viewer

Exemplo

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

Resposta

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

Erros

• 400 — role must be one of admin, editor, viewer
• 400 — endereço de e-mail inválido ou em falta
• 400 — seat limit reached — a conta não tem lugares livres para o plano (Free: 2, Starter: 5, Pro: 20, incluindo o proprietário). Remova um membro ou atualize o plano.
• 400 — o e-mail já é membro ou tem um convite pendente nesta conta

---

Aceitar convite

Aceite um convite pendente. O e-mail do utilizador autenticado tem de corresponder ao endereço para o qual o convite foi enviado.

POST /members/accept

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
inviteId	string	Sim	O ID do convite do e-mail com a ligação de aceitação

Exemplo

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

Resposta

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

Erros

• 400 — email does not match invitation — o e-mail com que iniciou sessão difere do e-mail convidado
• 404 — convite não encontrado (já aceite, cancelado, ou o inviteId está incorreto)

---

Atualizar função do membro

Altere a função de um membro existente. Requer privilégios de proprietário ou administrador.

POST /members/{memberId}/role

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
memberId	string	Sim	O ID do membro (parâmetro de caminho)
role	string	Sim	Nova função — uma de admin, editor, viewer

Exemplo

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

Resposta

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

Erros

• 400 — role must be one of admin, editor, viewer
• 400 — the owner role cannot be changed
• 404 — membro não encontrado

---

Remover membro

Remova um membro da conta ou cancele um convite pendente. O membro perde o acesso imediatamente e o seu lugar fica livre.

DELETE /members/{memberId}

Exemplo

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

Resposta

Uma string simples:

"member has been removed"

Erros

• 400 — the owner cannot be removed
• 404 — membro não encontrado