# Autenticação e chaves

> Como autenticar na API do Couryo com chaves ck_live_ e ck_test_, escopos, IPs permitidos e boas práticas.

Fonte: https://couryo.com/docs/authentication

Toda chamada para `https://api.couryo.com/v1` usa uma chave de API no cabeçalho `Authorization`:

```http title="Cabeçalho"
Authorization: Bearer ck_live_...
```

## Tipos de chave

| Prefixo | Modo | O que acontece |
|---|---|---|
| `ck_live_` | produção | entrega de verdade |
| `ck_test_` | teste | nunca entrega: o e-mail fica capturado no painel com status `captured` |

## Escopos

| Escopo | Pode |
|---|---|
| `send` | enviar e checar e-mails (`POST /v1/emails`, `/v1/emails/batch` e `/v1/emails/check`); não lê nada |
| `read` | ler e-mails, eventos, domínios, webhooks e supressões; não envia |
| `admin` | tudo, inclusive criar e verificar domínios, criar e mudar webhooks e mexer na lista de supressão |

Use o menor escopo possível. O servidor da sua aplicação normalmente só precisa de `send`; para consultar a linha do tempo de um e-mail, use uma chave `read`. As chaves valem para um projeto: cada projeto tem as suas.

## IPs permitidos

Cada chave pode ter uma lista de IPs permitidos (endereços ou faixas CIDR). Uma chamada de outro endereço recebe `403` com o código `ip_not_allowed`.

## Como guardamos sua chave

- A chave inteira aparece **uma única vez**, na criação. Depois, o painel mostra só o prefixo (por exemplo, `ck_live_4f9a`).
- O Couryo guarda apenas um hash da chave. Se perder, crie outra e apague a antiga.
- Uma chave apagada para de funcionar na hora (`401 invalid_api_key`).

## Boas práticas

- Guarde a chave em variável de ambiente ou num gerenciador de segredos. Nunca no código do navegador ou do app móvel.
- Uma chave por aplicação e por ambiente: fica fácil trocar uma sem derrubar as outras.
- Proteja a conta Google que você usa para entrar no painel com verificação em duas etapas e defina um [limite de gasto](https://couryo.com/docs/limits.md#limite-de-gasto).

## Erros de autenticação

| HTTP | `code` | Quando |
|---|---|---|
| 401 | `missing_api_key` | sem o cabeçalho `Authorization` |
| 401 | `invalid_api_key` | chave inexistente, apagada ou mal copiada |
| 403 | `insufficient_scope` | a chave não tem o escopo necessário |
| 403 | `ip_not_allowed` | a chamada veio de um IP fora da lista |

Veja todos os códigos em [Erros](https://couryo.com/docs/errors.md).