Sign inGet Started

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.

ControleO que ele limitaO que quem chama recebe ao atingir o limiteQuem o define
CredencialAs operações que o agente pode chamar403A pessoa que cria a chave ou aprova o login
Chave de idempotênciaEnvios duplicados quando uma solicitação é repetidaA resposta original, reproduzida novamenteQuem faz a chamada, em cada solicitação
Lista de destinos permitidos de SMSOs países para os quais um envio API de SMS pode ir422 SMSDestinationNotEnabledUma credencial com permissão de escrita em sms_management
Limite diário de gastos de SMSGastos de SMS com um país em um dia422 SMSDestinationDailySpendExceededUma credencial com permissão de escrita em sms_management
Carteira pré-pagaGastos pré-pagos por uso402 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 em BIRD_API_KEY quando 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 em api_keys, escrita em sms_management e 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 login solicita acesso somente leitura. --scope solicita o conjunto que você indicar, e --yolo solicita 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_at ao criá-la, e a chave passa a retornar 401 depois 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:

Exemplo de código
bird auth login --scope api_keys:write --scope sms:write
bird api-keys create --name "Support agent" --scope sms:write

Autenticaçã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:

Exemplo de código
bird sms destinations update --destination NL=true

Para 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:

Exemplo de código
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 como rejected e 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 402 até 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