---
title: Chaves de API
description: 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.
ai:
  exclude: true
---

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.

```sh
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](/docs/pt-br/team-roles). 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](/docs/pt-br/inboxes) a que a chave fica limitada.

Pela API:

```sh
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](#restringir-uma-chave-a-um-dominio) 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](/docs/pt-br/inboxes) 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](/docs/pt-br/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](/docs/pt-br/api-reference/basics). |

## 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](/docs/pt-br/team-roles).

Criar, renomear e revogar uma chave ficam registrados no [registro de auditoria](/docs/pt-br/audit-log).

## Outras chaves

- As **credenciais SMTP** são chaves só de envio criadas na página **SMTP** para o [relay SMTP](/docs/pt-br/smtp).
- As **chaves de agente** (`bs_agent_…`) são só para o [servidor MCP](/docs/pt-br/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.
