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.