Controles de agentes: chaves com escopo, limites de gastos e novas tentativas seguras
Um agente que envia pelo Bird tem uma credencial e gasta o seu saldo. Cinco controles limitam o que ele pode fazer. O primeiro é a própria credencial. Os outros quatro só valem enquanto a credencial do agente não puder alterá-los, então comece pela credencial.
| Controle | O que ele limita | O que quem chama recebe ao atingir o limite | Quem o define |
|---|---|---|---|
| Credencial | As operações que o agente pode chamar | 403 | A pessoa que cria a chave ou aprova o login |
| Chave de idempotência | Envios duplicados quando uma solicitação é repetida | A resposta original, reproduzida novamente | Quem faz a chamada, em cada solicitação |
| Lista de destinos permitidos de SMS | Os países para os quais um envio API de SMS pode ir | 422 SMSDestinationNotEnabled | Uma credencial com permissão de escrita em sms_management |
| Limite diário de gastos de SMS | Gastos de SMS com um país em um dia | 422 SMSDestinationDailySpendExceeded | Uma credencial com permissão de escrita em sms_management |
| Carteira pré-paga | Gastos pré-pagos por uso | 402 para SMS e WhatsApp. O email pago é cobrado depois de enviado. | Um proprietário da organização ou administrador de faturamento |
A lista de destinos permitidos e o limite diário de gastos desta página se aplicam a SMS. Verify e Voice têm cada um suas próprias configurações de destino, com um estado inicial diferente. Email e WhatsApp não têm lista de destinos permitidos nem limite diário de gastos, então são os escopos da credencial e a carteira que limitam um agente nesses canais.
Escolha a credencial que o agente usa
Um agente chama Bird com um de dois tipos de credencial. Eles diferem no alcance que têm.
- Uma chave API (
bk_) tem os escopos que você atribui a ela e pertence a um único espaço de trabalho. Ela não pode emitir outra chave nem acessar o faturamento, os membros ou as configurações da organização. Seu código a envia como bearer token. O CLI e o servidor MCP local (bird mcp) usam a chave emBIRD_API_KEYquando ela está definida, em vez de um login armazenado. - Um token OAuth (
bt_) é o que o CLI e o servidor MCP guardam depois que uma pessoa faz login. Ele tem as permissões que essa pessoa aprovou, nunca mais do que ela própria tem. Elas podem incluir escrita emapi_keys, escrita emsms_managemente o faturamento da organização. Um agente com um token assim pode emitir chaves, habilitar países e aumentar os limites desta página.
O quanto um token OAuth pode fazer depende de como ele foi criado:
bird auth loginsolicita acesso somente leitura.--scopesolicita o conjunto que você indicar, e--yolosolicita todas as permissões que você pode delegar. Você aprova o resultado no navegador.- Um cliente MCP hospedado pode solicitar todas as permissões que você pode delegar. A tela de consentimento permite selecionar quais conceder. Desmarque as que o agente não precisa antes de aprovar.
- Cadastro self-service não tem tela de consentimento. A credencial que ele cria tem todas as permissões que o proprietário da nova organização pode delegar, incluindo o faturamento da organização.
Para um agente que roda sem supervisão, crie uma chave API com escopo restrito e entregue essa chave ao agente. Deixe o login mais amplo com a pessoa que configura o espaço de trabalho. Você pode revogar o login de uma ferramenta em Profile > Connected apps. Chaves API e tokens OAuth compara os dois tipos de credencial.
Limite o escopo de cada chave aos produtos de que ela precisa
Uma chave API tem uma lista de escopos, cada um uma área de produto no nível read ou write. Uma chave que só envia SMS tem sms:write. Uma solicitação fora dos escopos da chave retorna 403, então uma chave vazada ou mal utilizada alcança apenas o que você concedeu a ela.
Três propriedades valem para qualquer chave, sejam quais forem seus escopos:
- Uma chave não pode emitir outra chave. Emitir e rotacionar chaves exige
api_keys:write, que não está disponível para chaves API. Uma pessoa aprova isso em uma sessão do dashboard ou em um login do CLI ou do MCP. - Uma chave fica restrita ao seu espaço de trabalho. Ela não alcança o faturamento, os membros da organização nem as configurações da organização.
- Uma chave pode expirar. Defina
expires_atao criá-la, e a chave passa a retornar401depois desse momento. Você pode rotacionar ou revogar uma chave a qualquer momento.
Crie uma chave no dashboard ou pelo terminal. Um login do CLI só pode atribuir a uma chave os escopos que ele mesmo tem, por isso este solicita sms:write além de api_keys:write:
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:writeAutenticação e chaves API traz a tabela de escopos e explica expiração, rotação e revogação.
Tente novamente um envio sem enviar duas vezes
Um agente que perde uma resposta não consegue saber se sua solicitação foi aceita. Envie um cabeçalho Idempotency-Key com um valor único para cada envio pretendido e, quando o resultado for desconhecido, repita a mesma solicitação com a mesma chave. O Bird retorna a resposta original e aceita a mensagem uma única vez. Uma resposta reproduzida contém Idempotency-Replay: true.
A garantia é de uma operação aceita por chave dentro da janela de retenção. Ela cobre a aceitação pela API. A entrega ao telefone é informada separadamente, pelo status da mensagem e pelos seus eventos.
Os SDKs geram uma chave para cada chamada que altera dados e a reutilizam nas suas novas tentativas automáticas. Na CLI, passe --idempotency-key. Idempotência explica o formato da chave, a janela de retenção e o que acontece quando uma chave é reutilizada com uma solicitação diferente.
Permita cada país de destino de SMS
A lista de permissões de destinos de SMS nega por padrão. Um envio pela SMS API vai para um país habilitado na lista ou é rejeitado com 422 SMSDestinationNotEnabled antes de o remetente ser definido, de modo que nenhuma mensagem é aceita. Um agente direcionado a um país inesperado é recusado. Isso vale para envios do seu próprio código, de bird sms send e da ferramenta sms_send MCP.
Os códigos de verificação não usam essa lista. O Verify tem sua própria lista em Verify destinations, onde todos os países começam habilitados. Por isso, uma credencial com permissão de escrita em verify pode enviar um código por SMS para um país que esta lista de permissões bloqueia. Se o agente tiver verify, desative também nessa página os países que você não atende.
Habilite um país em SMS > Destinations, com bird sms destinations update ou com a ferramenta sms_destinations_update MCP:
bird sms destinations update --destination NL=truePara alterar a lista de permissões, é preciso o escopo sms_management no nível write. Uma credencial que tem apenas sms pode enviar para os países habilitados, mas não pode habilitar outros. Dê ao agente que envia sms e reserve sms_management para a credencial que configura o espaço de trabalho.
Envio de SMS explica como a lista de permissões começa e como o país de origem é adicionado.
Limite o gasto diário com SMS para cada país
Cada país de destino pode ter um limite de gasto diário, na moeda da sua carteira. Quando o gasto do dia com esse país atinge o limite, novas mensagens para ele são recusadas com 422 SMSDestinationDailySpendExceeded até a meia-noite UTC. Um limite de zero bloqueia o país.
Os códigos de verificação enviados por SMS contam para o limite. Quando o limite é atingido, o Verify para de enviar códigos por SMS para esse país e tenta o próximo canal habilitado para ele. Quando não resta nenhum canal, a verificação falha com 422 NoAvailableChannel.
Defina um limite nos mesmos três lugares da lista de permissões. Este comando habilita a Holanda e a limita a 25 EUR por dia, em um espaço de trabalho cuja carteira está em EUR:
bird sms destinations update --destination "NL=true;25EUR"O limite não é exato. Uma alteração em um limite leva até um minuto para valer no envio. O gasto é contabilizado quando a mensagem é cobrada, então mensagens já aceitas podem levar o total do dia além do limite pelo valor que custam. Planeje o limite com essa margem. bird sms destinations list mostra o limite de cada país e o uso do dia em relação a ele.
Definir um limite exige o mesmo acesso de escrita sms_management que a allowlist, então uma credencial que tem apenas sms não consegue aumentar o próprio limite. Envio de SMS traz as regras completas.
Limite o gasto total com a carteira pré-paga
Envios pré-pagos por uso são debitados da carteira pré-paga da sua organização. O que acontece quando o saldo não cobre um envio depende do canal:
- SMS e WhatsApp são recusados na API com
402. Uma mensagem que já tinha sido aceita quando a cobrança falha termina comorejectede não é cobrada. - Email em um plano pago de Email é cobrado pouco depois do envio, então o saldo pode ficar negativo por um breve período. Quando a carteira não tem mais saldo nem crédito, novos emails são recusados com
402até que fundos sejam adicionados. - Uma tarifa cobrada na entrega que o saldo não cobre é ignorada, e a mensagem ainda chega ao destinatário.
Uma carteira vazia impede novos gastos, mas não limita o gasto exatamente ao saldo. Mantenha nela uma margem para envios cobrados depois de aceitos. Se a recarga automática estiver ativada, a carteira é recarregada a partir de um cartão salvo quando o saldo fica abaixo do seu limite mínimo, então o saldo sozinho deixa de limitar quanto um agente pode gastar. Faturamento e uso é a fonte dessas regras.
Operações de faturamento exigem a permissão de faturamento da organização, org:billing. Uma chave API não pode ter essa permissão, então nenhuma chave consegue recarregar a carteira, mudar de plano ou ler o uso. Um token OAuth pode tê-la quando a pessoa que aprova o login a possui e concede permissões da organização, como um proprietário da organização pode fazer. A credencial criada no cadastro self-service tem essa permissão desde o início. Dê a um agente que roda sem supervisão uma chave com escopo, e a adição de fundos continua com as pessoas responsáveis pelo orçamento.
Métodos de pagamento e carteira aborda recargas, recarga automática e alertas de saldo baixo.
Próximos passos
- Cadastro self-service: crie pelo terminal a conta em que um agente trabalha.
- Autenticação e chaves API: escopos, expiração, rotação e revogação.
- Limites de requisições: os limites de requisições que se aplicam a todas as chaves da sua organização.
- Dê a um agente o próprio número de telefone e a própria caixa de entrada: as identidades com as quais um agente envia e recebe mensagens.
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico.