Pular para o conteúdo
Esc
↑↓navegar↵abrir⌘Jpré-visualizar
Nesta página

Chaves de API

Crie chaves de API com acesso total ou só de envio, restrinja-as a um domínio ou a uma caixa de entrada e gerencie-as.

Uma chave de API é o segredo que o seu código envia em cada requisição. Crie uma em Chaves de API no painel, ou pela própria API. A chave é exibida uma única vez, na criação, então guarde-a no seu gerenciador de segredos.

curl https://api.billionsend.com/emails \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@example.com",
    "to": "ada@example.com",
    "subject": "Olá",
    "text": "Olá."
  }'

As chaves começam com bs_. O BillionSend guarda só um hash da chave, então uma chave perdida não pode ser exibida de novo: revogue-a e crie outra.

Criar uma chave

No painel, abra Chaves de API e escolha Criar chave de API. Proprietários, administradores e desenvolvedores podem fazê-lo; veja funções da equipe. Escolha:

  • Nome: de 1 a 80 caracteres, para você distinguir as chaves. Dá para renomeá-la depois.
  • Permissão: Acesso total ou Apenas envio.
  • Domínio: Qualquer domínio, ou um domínio verificado da sua equipe.
  • Restringir a uma caixa de entrada (aparece quando você tem caixas): a única caixa de entrada a que a chave fica limitada.

Pela API:

curl -X POST "https://api.billionsend.com/api-keys" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Produção",
    "permission": "sending_access",
    "domain_id": "af8ad875-319f-4df5-a359-4f2430f3e766"
  }'

A resposta é { "id": "…", "token": "bs_…" }: o token aparece só aqui. GET /api-keys lista as chaves ativas (nunca os tokens), e DELETE /api-keys/{id} revoga uma na hora; as requisições que a usam falham imediatamente.

Permissão

Permissão Pode
Acesso total Usar todos os endpoints: envio, contatos, segmentos, tópicos, broadcasts, domínios, webhooks, templates, e-mails recebidos e chaves de API. Uma chave restrita a um domínio alcança só uma parte disso.
Apenas envio Enviar e-mails (POST /emails, POST /emails/batch) e mais nada. Tudo fora do envio, e toda leitura de e-mails guardados, responde 403 restricted_api_key.

Use uma chave só de envio no app que envia e-mails transacionais. Uma chave só de envio vazada não lê os seus contatos, não altera os seus domínios e não cria outras chaves.

Restringir uma chave a um domínio

Uma chave restrita a um domínio trabalha dentro desse único domínio e não alcança nada que pertença à equipe inteira. O domínio precisa estar verificado antes de você restringir uma chave a ele; o subdomínio compartilhado das caixas de entrada não pode ser usado.

O quê O que a chave pode fazer
Envio, e-mails, e-mails recebidos, caixas de entrada, descadastros, broadcasts Só os desse domínio. Uma requisição para outro domínio responde 403 restricted_api_key.
GET /emails/metrics Lê só os números desse domínio; indicar outro domínio em domain_id responde 403 restricted_api_key.
GET /domains e /domains/{id} (ler, alterar, excluir, verificar) Lista e mexe só no próprio domínio. Qualquer outro domínio, inclusive o subdomínio compartilhado, responde 404.
/api-keys POST cria chaves restritas ao mesmo domínio. GET lista e DELETE revoga só chaves restritas a esse domínio; qualquer outra chave responde 404.
Contatos, segmentos, tópicos Permitido. Os contatos são a agenda compartilhada da equipe, mas a chave não pode desfazer um descadastro da equipe toda. Um segmento ou tópico que ela cria fica ligado ao próprio domínio, e ela não pode desligar um.
Webhooks (todos os métodos, inclusive o segredo de assinatura), supressões, templates, propriedades de contato, GET /usage, GET /deliverability, verificações e POST /domains 403 restricted_api_key: isso pertence à equipe inteira.

Use uma para um serviço que pertence a uma única marca: se ela vazar, alcança o domínio dessa marca e nada mais, nem os seus webhooks, nem as suas outras chaves, nem os seus outros domínios.

Restringir uma chave a uma caixa de entrada

Uma chave de caixa dá a um agente de IA acesso a uma caixa de entrada e a nada mais. Exige acesso total, não pode ser restrita também a um domínio, e só lê, responde, encaminha e envia rascunhos dessa caixa, e envia somente pelo endereço dela. Para de funcionar quando a caixa expira ou é excluída.

Limites

Limite Valor
Chaves ativas por equipe 25, credenciais SMTP incluídas. Revogue uma para criar outra (senão 422).
Chaves ativas por caixa 5, fora das 25 da equipe.
Requisições 600 por minuto por chave e 3.000 por equipe; veja Noções básicas da API.

Quem pode criar qual chave

  • No painel, proprietários, administradores e desenvolvedores criam chaves.
  • Uma chave que você cria pela API nunca é mais ampla que a chave que a criou: uma chave só de envio só cria chaves só de envio, uma chave restrita a um domínio só cria chaves desse domínio (e só vê e revoga essas), e uma chave de caixa não cria chaves.
  • Uma chave age com a função que o criador dela tem hoje na equipe, conferida a cada requisição. O criador é a pessoa que a fez no painel (ou conectou o app que a fez); uma chave criada pela API leva o criador da chave que a criou. A função não limita o trabalho do dia a dia: uma chave de acesso total envia e gerencia contatos, broadcasts, domínios, webhooks e chaves, qualquer que seja a função do criador (a chave restrita a um domínio é a exceção, veja acima). As ações de alto risco (apagar um destinatário, remover uma supressão, desfazer um descadastro) exigem uma chave cujo criador seja agora proprietário ou administrador; as outras chaves respondem 403 forbidden. Se o criador é rebaixado, as chaves dele seguem a nova função a partir da próxima requisição. Se ele é removido da equipe ou sai, todas as chaves de API que ele fez, as chaves que essas chaves fizeram e as chaves de agente dele deixam de funcionar na hora (401 invalid_api_key) e aparecem como revogadas; ser convidado de volta não as traz de volta. Veja funções da equipe.

Criar, renomear e revogar uma chave ficam registrados no registro de auditoria.

Outras chaves

  • As credenciais SMTP são chaves só de envio criadas na página SMTP para o relay SMTP.
  • As chaves de agente (bs_agent_…) são só para o servidor MCP. São criadas em MCP, ficam limitadas a somente leitura, leitura e resposta, ou leitura e envio, e uma equipe tem até 20. As suas chaves de API comuns não funcionam no servidor MCP.

Esta página foi útil?