# Chaves de API

> Crie chaves de API Full Access e Sending Only, restrinja-as a um domínio, use-as no SMTP e faça a rotação sem interrupção.

As chaves de API autenticam as suas requisições à API REST, as suas conexões SMTP e as sessões com chave de API no servidor MCP. Esta página explica os dois escopos de chave, como criar e gerenciar chaves e como guardá-las e fazer a rotação delas com segurança.

## Como as chaves de API funcionam

- Cada chave pertence a um workspace. Tudo o que você faz com ela acontece nesse workspace.
- As chaves novas começam com `secret_` seguido de 32 letras e dígitos, por exemplo, `secret_••••••••`. As chaves criadas antes da introdução do prefixo continuam funcionando.
- O Emailit mostra a chave completa uma única vez, quando você a cria ou regenera. Copie-a nesse momento; não é possível vê-la de novo.
- Envie a chave como bearer token: `Authorization: Bearer secret_…`. No SMTP, a chave é a senha.

## Escopos

Toda chave tem um de dois escopos. Você escolhe o escopo ao criar a chave.

| | Full Access (`full`) | Sending Only (`sending`) |
| --- | --- | --- |
| Enviar e-mails (`POST /emails`) | Sim | Sim |
| Reagendar, cancelar, tentar de novo e encaminhar um e-mail | Sim | Sim |
| SMTP relay | Sim | Sim |
| Ler e-mails (listar, obter, MIME bruto, corpo, metadados, anexos) | Sim | Não |
| Domínios, templates, contatos, listas de contatos, supressões, webhooks, eventos, campanhas, automações, verificação e chaves de API | Sim | Não |
| Ferramentas MCP | Todas as ferramentas | `send-email`, `update-email`, `cancel-email`, `retry-email`, `forward-email` e `get-current-workspace` |
| Pode ser restrita a um domínio de envio | Não | Sim |

Uma chave Sending Only que chama qualquer outro endpoint recebe `403` com uma mensagem como `Permission denied: read`. Use chaves Full Access para tarefas internas que gerenciam recursos e chaves Sending Only para tudo o que só precisa enviar.

### Restringir uma chave a um domínio

Ao criar uma chave Sending Only, você pode escolher um domínio de envio verificado. A chave passa a enviar apenas de endereços desse domínio:

- Pela API, enviar de outro domínio retorna `403` com `"error": "Domain not authorized"`.
- Pelo SMTP, a mensagem é rejeitada depois de `DATA` com `530 API key is restricted to sending domain: …`.

As chaves restritas são uma boa escolha para credenciais por aplicação ou por cliente, e para chaves que você precisa entregar a software de terceiros, como um plugin de CMS.

## Antes de começar

- É preciso ter o papel **Admin** no workspace para criar, editar, regenerar ou excluir chaves. Membros com o papel Member podem ver a lista de chaves, mas não alterá-la. Consulte [Membros e papéis](/pt/docs/workspaces/members-and-roles/).
- Para enviar com uma chave, você precisa de pelo menos um [domínio de envio verificado](/pt/docs/domains/add-a-domain/).

## Criar uma chave de API

**Painel**

  1. **Abra as chaves de API.** Acesse **Email API → API Keys** e selecione **Add API key**.

  2. **Dê um nome à chave.** Em **Name**, digite um nome que indique onde a chave é usada, por exemplo, `production-web` ou `wordpress-blog`. Os nomes devem ser únicos no workspace.

  3. **Escolha um escopo.** Em **Scope**, escolha **Full Access** ou **Sending Only**.

  4. **Se quiser, restrinja o domínio.** Para uma chave Sending Only, escolha um domínio de envio em **Domain** ou deixe o campo vazio para permitir todos os domínios verificados.

  5. **Crie e copie a chave.** Selecione **Create**. Copie a chave da caixa de diálogo e guarde-a no seu gerenciador de segredos antes de fechá-la. O Emailit mostra a chave uma única vez.

**API**

  Chame [Criar uma chave de API](/pt/docs/api-reference/api-keys/create/) com uma chave Full Access. O padrão de `scope` é `full`; `sending_domain_id` só se aplica a chaves Sending Only.

```bash
curl https://api.emailit.com/v2/api-keys \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-web",
    "scope": "sending",
    "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6"
  }'
```

  A resposta `201` é a única que inclui `key`:

```json
{
  "object": "api_key",
  "id": "key_4F2kN8sQwE1rT6yU3iO9pA7sD5f",
  "name": "production-web",
  "scope": "sending",
  "sending_domain_id": "dom_3xQ7mLp2RkT9vB4nHs8YcWd1Ze6",
  "last_used_at": null,
  "created_at": "2026-10-01T09:30:00.000Z",
  "updated_at": "2026-10-01T09:30:00.000Z",
  "key": "secret_••••••••••••••••••••••••••••••••"
}
```

  Um nome que já está em uso retorna `409`.

## Usar a chave

Passe a chave no cabeçalho `Authorization` de cada requisição à API:

```bash
curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "subject": "Your order has shipped",
    "text": "Your order #1042 is on its way."
  }'
```

Para enviar por SMTP, use a chave como senha:

| Configuração | Valor |
| --- | --- |
| Host | `smtp.emailit.com` |
| Porta | `587` (STARTTLS, recomendada), `465` (TLS), `2525` ou `2587` (STARTTLS) |
| Usuário | `emailit` |
| Senha | A sua chave de API |

Consulte [Configurações de SMTP](/pt/docs/smtp/settings/) para ver todas as opções.

## Gerenciar chaves

Abra uma chave em **Email API → API Keys** para ver o escopo, o domínio, a data em **Created**, o horário em **Last used** e as configurações de SMTP a usar com ela.

| Ação | O que acontece | API |
| --- | --- | --- |
| **Edit** | Renomeia a chave. Apenas o nome é salvo; para alterar o escopo ou a restrição de domínio, crie uma chave nova e faça a rotação para ela. | [Atualizar uma chave de API](/pt/docs/api-reference/api-keys/update/) |
| **Regenerate** | Gera um novo segredo para a mesma chave e o mostra uma única vez. O segredo antigo deixa de funcionar imediatamente. A chave mantém o ID, o nome, o escopo e o domínio, e **Last used** é zerado. | [Regenerar uma chave de API](/pt/docs/api-reference/api-keys/regenerate/) |
| **Delete** | A chave deixa de funcionar imediatamente e some da lista. Essa ação não pode ser desfeita. | [Excluir uma chave de API](/pt/docs/api-reference/api-keys/delete/) |

**Last used** é atualizado sempre que a chave autentica uma requisição à API ou um login SMTP. Uma chave que nunca foi usada mostra **Never**. Na API, os endpoints que recebem o ID de uma chave também aceitam o nome dela.

## Guardar as chaves com segurança

- **Mantenha as chaves no servidor.** Nunca coloque uma chave em JavaScript do navegador, em um app mobile, em um repositório público ou em um chamado de suporte. Qualquer pessoa com a chave pode enviar e-mails em seu nome e gastar os seus créditos.
- **Use variáveis de ambiente ou um gerenciador de segredos.** Carregue a chave em tempo de execução, por exemplo, de `EMAILIT_API_KEY`. Adicione os arquivos `.env` ao `.gitignore`.
- **Dê a cada aplicação e ambiente a sua própria chave.** Chaves separadas para produção, homologação e cada ferramenta de terceiros facilitam ver quem enviou o quê e revogar uma sem mexer nas outras.
- **Use o escopo mais restrito.** Se uma aplicação só envia e-mails, dê a ela uma chave Sending Only, restrita ao domínio dela sempre que possível.
- **Acompanhe o uso.** **Email API → Logs** lista as requisições à API e ao SMTP por chave, e você pode filtrar **Email API → Emails** por chave de API. Consulte [Logs de requisições](/pt/docs/logs/request-logs/).
- **Aja rápido em caso de vazamento.** Se uma chave for exposta, regenere-a ou exclua-a na hora e depois verifique nos logs se houve envios inesperados.

## Fazer a rotação de uma chave sem interrupção

Regenerar uma chave invalida o segredo antigo na hora, então faça isso só quando uma chave estiver comprometida. Para uma rotação planejada, use a chave antiga e a nova lado a lado:

1. **Crie uma chave nova.** Adicione uma chave com o mesmo escopo e a mesma restrição de domínio da chave que você vai substituir. Dê a ela um nome que indique a data, como `production-web-2026-10`.

2. **Faça o deploy da chave nova.** Atualize o segredo no seu gerenciador de segredos ou no ambiente e distribua-o para todos os servidores, workers e jobs agendados que usam a chave antiga.

3. **Confirme a troca.** Abra a chave nova e confira se **Last used** é recente. Em **Email API → Logs**, filtre pela chave antiga e confira se as requisições pararam.

4. **Exclua a chave antiga.** Quando o horário em **Last used** da chave antiga parar de mudar, exclua-a.

## Solução de problemas

| Sintoma | Causa | Solução |
| --- | --- | --- |
| `401` `Invalid API key` | A chave foi excluída, regenerada ou digitada errado. | Copie a chave atual para a sua configuração, incluindo o prefixo `secret_`. |
| `403` `Permission denied: read` ou `Permission denied: full` | Uma chave Sending Only chamou um endpoint fora do escopo dela. | Use uma chave Full Access para essa chamada. |
| `403` `Domain not authorized` | A chave está restrita a um domínio diferente do endereço `from`. | Envie do domínio da chave ou use outra chave. |
| SMTP `535 Authentication failed` | A senha não é uma chave de API válida. | Use a chave de API como senha e `emailit` como usuário. |

## Veja também

  - [Autenticação](/pt/docs/api-reference/authentication/): Como as requisições são autenticadas.
  - [API de chaves de API](/pt/docs/api-reference/api-keys/): Crie, liste, atualize, regenere e exclua chaves.
  - [Configurações de SMTP](/pt/docs/smtp/settings/): Host, portas, TLS e credenciais.
  - [Segurança](/pt/docs/security/): Como o Emailit protege a sua conta e os seus dados.

---
Fonte: https://emailit.com/pt/docs/developers/api-keys/