Usuários, equipes e funções
O acesso de pessoas no Bird é baseado em funções: um usuário possui uma função no seu espaço de trabalho, e cada função é um conjunto fixo de permissões. Nada mais precisa ser configurado; escolha a função certa e as permissões acompanham.
As funções determinam o que pessoas podem fazer no dashboard. O que serviços podem fazer é determinado pelos escopos de chave API: o mesmo vocabulário de permissões, concedido por chave em vez de por função.
Funções do espaço de trabalho
As funções com que você trabalha no dia a dia pertencem ao espaço de trabalho (veja Espaço de trabalho): admin, developer e analyst. Gerencie-as no dashboard em Settings > Team.
Cada permissão é um par {scope, level}, em que level é read ou write (write inclui read). Uma função é um conjunto fixo e nomeado desses pares:
| Escopo | O que write significa | admin | developer | analyst |
|---|---|---|---|---|
| workspace | Editar configurações do espaço de trabalho (nome, notificações) | write | read | read |
| api_keys | Criar e revogar chaves API | write | write | none |
| emails | Enviar e-mail | write | write | read |
| email_management | Gerenciar supressões e configuração de e-mail | write | write | read |
| email_marketing | Gerenciar contatos, audiências e broadcasts | write | write | read |
| domains | Adicionar, verificar e remover domínios de envio | write | write | read |
| webhooks | Configurar endpoints de webhook | write | write | read |
| sms | Enviar SMS | write | write | read |
| sms_management | Gerenciar remetentes, supressões e configurações de SMS | write | write | read |
| verify | Enviar e verificar códigos de verificação | write | write | read |
| verify_management | Configurar remetentes e países de verificação | write | write | read |
| Enviar mensagens WhatsApp | write | read | read | |
| whatsapp_management | Gerenciar templates e configurações de WhatsApp | write | write | read |
| assets | Fazer upload, atualizar e excluir assets e pastas | write | write | read |
| compliance | Gerenciar identidades de registro, envios e evidências | write | write | read |
| lookup | Consultar números de telefone, endereços de e-mail e correspondências de identidade | write | write | none |
| mailbox | Enviar e responder mensagens de caixa de entrada | write | write | read |
| mailbox_management | Criar, atualizar e excluir caixas de entrada e regras de recebimento | write | write | read |
| realtime | Criar apps e publicar eventos | write | write | read |
| voice | Ler logs de chamadas e estatísticas, e realizar chamadas | write | write | read |
| voice_management | Gerenciar trunks, gateways, números, caller IDs e destinos | write | write | read |
| ip_pools | Visualizar os pools de IP da organização (somente leitura) | read | read | read |
| members | Gerenciar o time e os convites do espaço de trabalho | write | read | read |
| analytics | Visualizar relatórios e análises de entregabilidade | read | none | read |
| audit | Visualizar o log de auditoria | read | none | read |
| request_logs | Visualizar o log de solicitações (somente leitura) | read | read | read |
Na prática, um admin administra o espaço de trabalho, incluindo a equipe e as configurações. Um developer pode criar integrações, gerenciar domínios e webhooks e criar chaves API. Um analyst tem acesso somente leitura.
Duas linhas merecem atenção. ip_pools é somente leitura mesmo para admins, porque a compra de IPs dedicados e o gerenciamento de pools exigem o escopo org:ip_pools:write no nível da organização. As permissões de WhatsApp também separam gerenciamento de envio de mensagens. Um developer pode gerenciar templates e configurações com whatsapp_management:write, mas só pode ler mensagens com whatsapp:read; o envio permanece restrito a admins. Outros produtos adicionam escopos usando o mesmo modelo {scope, level}.
Um 403 de qualquer endpoint significa que o principal autenticado não possui o {scope, level} que o endpoint exige. A solução é uma mudança de função (para uma pessoa) ou uma nova chave com os escopos corretos (para um serviço).
Funções da organização
Por trás do seu espaço de trabalho existe uma organização que é dona do faturamento e da lista geral de membros. Duas funções gerenciam essa camada:
- owner: tudo. Leitura e escrita completas em operações de organização e espaço de trabalho. Uma organização pode (e deve) ter vários owners. A pessoa que criou a conta começa como owner.
- billing_admin: faturamento e configurações da organização (org:billing:write, org:settings:write) mais acesso de leitura à lista de membros da organização e aos metadados do espaço de trabalho. Sem acesso a recursos dentro do espaço de trabalho.
Essas funções raramente aparecem no dia a dia: a maioria dos colegas só precisa de uma função de espaço de trabalho.
Membros e a equipe
A associação é implícita: um usuário é "in" da sua organização se possuir uma função de organização ou uma função de espaço de trabalho. Não existe um registro de associação separado para gerenciar.
Você gerencia as pessoas do seu espaço de trabalho no dashboard em Settings > Team, protegido pelo escopo members do espaço de trabalho; um admin do espaço de trabalho gerencia a equipe aqui sem precisar de nenhuma função no nível da organização. Gerenciamento de equipe é algo que pessoas fazem, então chaves API não podem ter o escopo members (veja Autenticação).
Remover o acesso de alguém ao espaço de trabalho remove apenas esse papel, sem alterar nenhum papel de organização que a pessoa possua. Remover alguém da organização revoga todo o acesso à conta. As chaves API que a pessoa criou continuam funcionando porque cada chave pertence ao espaço de trabalho independentemente de quem a criou.
Convites
Em Settings > Team, convide um endereço de e-mail com um papel, e Bird resolve o resto. Por trás do botão existe um convite inteligente: um único fluxo atende tanto colegas que já fazem parte da sua organização quanto pessoas que nunca ouviram falar de Bird.
- Já é membro da organização: a pessoa é adicionada ao espaço de trabalho imediatamente com a função escolhida. Sem e-mail, sem espera; a resposta é um objeto de membro.
- Ainda não é membro: Bird cria um convite, envia por e-mail um link de cadastro, e a resposta é um objeto de convite com status pending. O link é válido por 7 dias; depois disso o convite expira e você convida a pessoa novamente.
O campo type da resposta (team_member ou invitation) indica o que aconteceu. Um segundo convite pendente para o mesmo e-mail retorna 409 em vez de criar uma duplicata, e você pode retirar um convite pendente a qualquer momento na mesma página.
Um owner pode convidar outro owner ou billing_admin. Esse convite exige org:members:write, que apenas owners possuem.
Proteções
Duas invariantes são aplicadas em toda mudança de função, independentemente de quem solicita:
- O último owner não pode ser movido. Rebaixar ou remover o único owner de uma organização retorna 409: uma organização nunca pode ficar sem owner. Promova um segundo owner primeiro.
- Você não pode alterar seu próprio acesso. Alterar sua própria função ou remover a si mesmo retorna 403. Isso evita tanto o bloqueio acidental de si mesmo quanto a autopromoção silenciosa; outro admin ou owner precisa fazer a alteração.
Como o contexto é selecionado
Endpoints de membros e equipe existem em dois níveis, e qual organização ou espaço de trabalho uma solicitação tem como alvo depende de como ela se autentica:
- Autenticação por sessão (o dashboard, ou ferramentas agindo como você) fornece o contexto por solicitação: X-Organization-Id em endpoints com escopo de organização, X-Workspace-Id em endpoints com escopo de espaço de trabalho.
- Chaves API carregam seu contexto implicitamente. Uma chave pertence ao seu espaço de trabalho, o que também fixa a organização; nenhum header é necessário, e um header de contexto que contradiga a chave é rejeitado como malformado (400).
Veja Espaço de trabalho para o modelo completo de resolução de contexto.
Próximos passos
- Autenticação e chaves API: escopos para serviços e quem pode gerenciar chaves
- Espaço de trabalho: o espaço de trabalho ao qual essas funções se vinculam
- Faturamento e uso: o que as funções de faturamento no nível da organização gerenciam
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.