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

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.

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.