API de membros

Gerencie os assentos de equipe e as funções — as pessoas que compartilham os emissores, distintivos e concessões da sua conta.

Todos os endpoints exigem autenticação. Consulte Autenticação. Cada requisição é restrita ao escopo da conta do proprietário autenticado.

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

Listar membros

Recupere 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 aceitos.

---

Convidar membro

Convide uma pessoa para a conta por e-mail. Um e-mail de convite com um link de aceitação é enviado ao endereç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 ausente
• 400 — seat limit reached — a conta não tem assentos livres para o plano (Free: 2, Starter: 5, Pro: 20, incluindo o proprietário). Remova um membro ou faça upgrade do plano.
• 400 — o e-mail já é membro ou tem um convite pendente nesta conta

---

Aceitar convite

Aceite um convite pendente. O e-mail do usuário autenticado deve 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 o link 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 fez login difere do e-mail convidado
• 404 — convite não encontrado (já aceito, 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 seu assento é liberado.

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