# Autenticação

> Autentique as requisições à API com uma chave de API ou um token de acesso OAuth como Bearer, escolha o escopo full ou sending, restrinja chaves a um domínio e trate os erros de autenticação.

Toda requisição à API do Emailit precisa levar uma credencial no cabeçalho `Authorization`. Esta página explica os dois tipos de credencial (chaves de API e tokens de acesso OAuth), o que cada escopo permite fazer e todos os erros de autenticação que você pode receber.

## Chaves de API

Uma chave de API pertence a um workspace, e toda requisição feita com ela atua nesse workspace. As chaves têm esta aparência:

```text
secret_Xq7pL2mN9vB4kR8tW1yZ6cH3jF5dS0aG
```

Ou seja, `secret_` seguido de 32 letras e dígitos. Chaves criadas antes do formato `secret_` não têm prefixo e continuam funcionando.

Crie chaves no painel em **Email API → API Keys** ou com [Criar uma chave de API](/pt/docs/api-reference/api-keys/create/). O segredo é exibido uma única vez, quando você cria ou [regenera](/pt/docs/api-reference/api-keys/regenerate/) a chave, então guarde-o imediatamente. Consulte [Chaves de API](/pt/docs/developers/api-keys/) para gerenciá-las.

As mesmas chaves funcionam como senha SMTP no [SMTP relay](/pt/docs/smtp/settings/).

## Enviar a chave em cada requisição

Use o esquema `Bearer` no cabeçalho `Authorization`. A API não aceita chaves em parâmetros de consulta nem no corpo da requisição.

**cURL**

```bash
curl https://api.emailit.com/v2/domains \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const response = await fetch('https://api.emailit.com/v2/domains', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const domains = await response.json();
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.emailit.com/v2/domains",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
domains = response.json()
```

Quando você passa a chave para o cliente, os SDKs definem esse cabeçalho por você.

## Escopos

Cada chave tem um de dois escopos. Você o escolhe ao criar a chave e não pode alterá-lo depois.

| Escopo | Pode chamar | Use para |
| --- | --- | --- |
| `full` | Todos os endpoints da API. É o padrão. | Ferramentas internas, scripts e integrações que gerenciam domínios, contatos, templates ou webhooks. |
| `sending` | Apenas os endpoints de envio listados abaixo. | Servidores de aplicação que só enviam e-mails. |

Uma chave `sending` pode chamar estes endpoints e nenhum outro:

| Endpoint | Descrição |
| --- | --- |
| `POST /emails` | [Enviar um e-mail](/pt/docs/api-reference/emails/send/) |
| `POST /emails/{id}` | [Atualizar um e-mail agendado](/pt/docs/api-reference/emails/update/) |
| `POST /emails/{id}/cancel` | [Cancelar um e-mail](/pt/docs/api-reference/emails/cancel/) |
| `POST /emails/{id}/retry` | [Tentar enviar um e-mail de novo](/pt/docs/api-reference/emails/retry/) |
| `POST /emails/{id}/forward` | [Encaminhar um e-mail](/pt/docs/api-reference/emails/forward/) |

Ler e-mails (listar, obter, MIME bruto, corpo, metadados, anexos e status) exige uma chave `full`. Quando uma chave `sending` chama qualquer outro endpoint, a API retorna `403` com `Permission denied: full` (ou `Permission denied: read` nos endpoints de leitura de e-mails).

A página [Todos os endpoints](/pt/docs/api-reference/endpoints/) mostra o escopo de cada endpoint.

## Restringir uma chave a um domínio

Uma chave `sending` também pode ficar presa a um único domínio de envio. Passe o ID do domínio em `sending_domain_id` ao [criar a chave](/pt/docs/api-reference/api-keys/create/). Uma chave restrita só pode enviar de endereços desse domínio. Qualquer outro domínio em `from` retorna `403`:

```json
{
  "error": "Domain not authorized",
  "message": "API key is not authorized to send from this domain"
}
```

As restrições de domínio se aplicam apenas a chaves `sending`. Uma chave `full` sempre tem acesso a todos os domínios do workspace.

## Tokens de acesso OAuth

Apps que agem em nome de um usuário do Emailit, como clientes MCP e integrações de terceiros, não pedem uma chave de API. Em vez disso, eles usam OAuth 2.1: o usuário entra no Emailit, escolhe os workspaces que o app pode usar (todos ou apenas os selecionados) e aprova o escopo `sending` ou `full`, e o app recebe um token de acesso. O usuário pode alterar ou revogar esse acesso em [Connected apps](/pt/docs/account/connected-apps/).

Envie os tokens de acesso no mesmo cabeçalho das chaves de API:

```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…
```

Um token de acesso vale por 15 minutos e atua no workspace padrão da autorização, com o escopo concedido e o papel do usuário nesse workspace. Os apps o renovam com o token de atualização. Consulte [Apps OAuth](/pt/docs/developers/oauth-apps/) para criar um.

## Erros de autenticação

A autenticação é executada antes de qualquer outra coisa, então esses erros podem vir de qualquer endpoint.

| Status | `message` ou `error` | Causa | Solução |
| --- | --- | --- | --- |
| `401` | `API key required` | O cabeçalho `Authorization` está ausente ou não começa com `Bearer `. | Envie `Authorization: Bearer <key>`. |
| `401` | `Valid API key required` | O cabeçalho tem o prefixo `Bearer`, mas nenhum token. | Verifique se a variável que guarda a sua chave não está vazia. |
| `401` | `Invalid API key` | A chave não existe, foi excluída ou foi regenerada (o segredo antigo para de funcionar), ou um token OAuth expirou. | Use uma chave atual ou renove o token OAuth. |
| `403` | `Workspace is suspended` | O workspace está suspenso. | Fale com o [suporte](/contact/). |
| `403` | `Permission denied: full` | Uma chave `sending` chamou um endpoint que exige `full`. | Use uma chave `full`. |
| `403` | `Domain not authorized` | Uma chave restrita a um domínio enviou de outro domínio. | Envie do domínio da chave ou use outra chave. |
| `403` | `unverified_workspace_recipient` | O workspace ainda não foi verificado e um destinatário não é membro do workspace. | Consulte [Workspaces não verificados](#unverified-workspaces). |
| `503` | `Authentication service unavailable` | Um problema temporário do nosso lado. | Tente de novo com backoff. |

**401**

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

**403 Escopo**

```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Permission denied: full"
}
```

**403 Suspenso**

```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Workspace is suspended"
}
```

**403 Não verificado**

```json
{
  "code": "unverified_workspace_recipient",
  "error": "Workspace not verified",
  "message": "Unverified workspaces can only send to workspace members' account emails. Blocked recipient: ada@example.com.",
  "blocked_recipients": ["ada@example.com"]
}
```

## Workspaces não verificados

Workspaces novos começam não verificados. Até o Emailit aprovar o [acesso de produção](/pt/docs/workspaces/production-access/), a API só envia para os endereços de e-mail das contas dos membros do workspace. Enviar, tentar de novo ou encaminhar para qualquer outra pessoa retorna `403` com o código `unverified_workspace_recipient` e a lista `blocked_recipients`, e as campanhas não podem ser enviadas de forma alguma. As suas chaves de API funcionam normalmente para todo o resto.

## Manter as chaves em segredo

Uma chave de API dá acesso ao seu workspace, então trate-a como uma senha.

- Chame a API apenas do seu servidor. Nunca coloque uma chave em JavaScript de navegador, em um app para celular nem em qualquer outro código que rode no dispositivo de outra pessoa.
- Mantenha as chaves fora do controle de versão. Carregue-as de variáveis de ambiente ou de um gerenciador de segredos.
- Crie uma chave por aplicação e por ambiente, com um nome que indique onde ela é usada, para poder revogar uma sem quebrar as outras.
- Dê a cada chave apenas o acesso de que ela precisa: uma chave `sending` restrita a um domínio é suficiente para a maioria das aplicações.
- Confira `last_used_at` em [Listar chaves de API](/pt/docs/api-reference/api-keys/list/) e exclua as chaves que você não usa mais.
- Se uma chave vazar, [regenere](/pt/docs/api-reference/api-keys/regenerate/) ou [exclua](/pt/docs/api-reference/api-keys/delete/) a chave imediatamente. O segredo antigo para de funcionar na hora.

## Veja também

  - [Chaves de API](/pt/docs/developers/api-keys/): Crie, restrinja e faça a rotação de chaves no painel.
  - [Erros](/pt/docs/api-reference/errors/): Todos os formatos de erro e códigos de status.
  - [Apps OAuth](/pt/docs/developers/oauth-apps/): Permita que usuários conectem a sua aplicação ao workspace deles.
  - [Acesso de produção](/pt/docs/workspaces/production-access/): Verifique o seu workspace para enviar para qualquer pessoa.

---
Fonte: https://emailit.com/pt/docs/api-reference/authentication/