Começar

Autenticação

Toda chamada leva uma chave de API no header Authorization. A chave identifica a conta, o ambiente e o que aquela integração tem permissão de fazer.

O header

http

Authorization: Bearer <sua-chave>

É o único jeito de autenticar na API. Não existe chave em query string, de propósito: parâmetro de URL vaza em log de servidor, em histórico de navegador e no header Referer.

Os dois prefixos

Prefixo	Ambiente
`sm_test_`	Desenvolvimento e homologação
`sm_live_`	Produção

O prefixo é visível no painel e nos seus logs, e é o que deixa óbvio, de relance, se aquele servidor está apontando para o lugar certo. A chave inteira aparece uma única vez, no momento em que é criada: guardamos só o hash SHA-256, então não temos como mostrar de novo nem para você. Perdeu, cria outra e revoga a antiga.

Para simular entrega, devolução e reclamação sem gastar reputação, o que muda não é o prefixo da chave e sim o destinatário: ver Modo de teste.

Permissão da chave

Uma chave pode ser completa ou só de envio. A de envio passa em POST /v1/messages e é recusada em qualquer outra rota, inclusive na que cria outras chaves.

Use a de envio no servidor que dispara e-mail. Se essa máquina for comprometida, o atacante manda e-mail em seu nome, o que já é ruim, mas não lista os seus domínios, não lê o seu histórico de mensagens e não cria uma chave nova para se manter dentro.

Escopo por domínio

Uma chave pode ainda ser presa a um domínio verificado. Nesse caso ela só envia com remetente daquele domínio. É o que separa um cliente do outro quando você opera em nome de terceiros.

Criar e revogar

shell

curl -X POST https://api.jetsend.com.br/v1/api-keys \  -H "Authorization: Bearer $JETSEND_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "nome": "produção, servidor de faturas" }'

GET /v1/api-keys lista as chaves da conta, sempre sem o valor: nome, prefixo, permissão, data de criação e data do último uso. Esse último campo é o que responde se dá para revogar uma chave sem derrubar nada.

DELETE /v1/api-keys/:id revoga. A revogação vale na chamada seguinte, não há janela de cache.

Papéis de pessoas

Chave de API é uma coisa; pessoa logada no painel é outra. Cada pessoa tem um papel na conta:

admin, faz tudo, inclusive adicionar domínio, convidar gente e mexer em cobrança.
member, envia e lê, mas não mexe na configuração da conta.
viewer, só lê.

Uma tentativa recusada por papel devolve 403. Chave ausente, malformada ou revogada devolve 401.