Chaves de API
As senhas que seus sistemas usam para falar com a Postal: criar, limitar e revogar.
Para que serve
Uma chave de API é a senha que seu sistema usa para falar com a Postal, pela API (cabeçalho Authorization: Bearer ps_...) ou por SMTP. Esta área cria, lista e revoga chaves e mostra o que cada uma tem feito.
Quando usar: Ao integrar um sistema novo, ao dar acesso restrito a um app e ao responder "quem fez essa chamada?".
#Lista de chaves
Onde fica: Desenvolvedores › Chaves de API. Endereço: app.postal.so/api-keys.
| Item | O que faz |
|---|---|
| Ver código | Mostra como criar uma chave pela API (POST /api-keys). |
| Criar chave | Abre o cadastro (veja abaixo). Sem nenhum domínio no time, o botão vira Adicionar domínio: a chave envia pelos domínios do time e ainda não há nenhum. |
| Buscar por nome ou início da chave | Procura pelo nome ou pelos primeiros caracteres (ps_ab12). |
| Filtros › Permissão | Acesso total ou Somente envio. |
| Exportar | Gera um CSV das chaves (nunca com o token). |
| Coluna | O que mostra |
|---|---|
| Nome | O nome que você deu (link para o detalhe). |
| Chave | Só o início (ps_ab12…), para reconhecer a chave. O token completo nunca é mostrado de novo. |
| Permissão | Acesso total ou Envio (com o nome do domínio, quando a chave é restrita a um). |
| Usos | Quantas requisições a chave já fez. |
| Último uso | Há quanto tempo foi usada pela última vez. Uma chave que não é usada há meses é candidata a ser revogada. |
| Criada em | Quando foi criada. |
| Lixeira | Revogar ...: as aplicações que usam a chave deixam de funcionar imediatamente. |
Abaixo da tabela, o lembrete de que as mesmas chaves servem de senha para enviar por SMTP, com o link Ver credenciais SMTP.
Criar uma chave
- Clique em Criar chave, dê um Nome (até 50 caracteres; sugestão: um nome por sistema e por ambiente, como "Produção" ou "Loja").
- Escolha a Permissão (veja abaixo) e, nas chaves só de envio, o Domínio (opcional) a que ela fica restrita.
- Clique em Criar chave. A tela Chave criada mostra o token uma única vez (Copie a chave agora. Por segurança, ela não será mostrada novamente.), com o botão de copiar. Guarde-a numa variável de ambiente e clique em Concluído.
Veja também: Autenticação · Chaves de API (API) · SMTP.
#Permissões e detalhe da chave
Permissões
| Permissão | O que a chave pode |
|---|---|
| Acesso total | Envia e lê e-mails, domínios, chaves, webhooks e o resto da API. Reserve para automações de infraestrutura e para o servidor do seu produto. |
| Somente envio | Só envia e-mails (POST /emails, POST /emails/batch), eventos (POST /events) e SMTP; também consulta os e-mails que ela mesma enviou e o plano e as cotas em GET /usage. Não lê e-mails de outras chaves, domínios, contatos nem outras chaves. |
| Domínio | Em chaves só de envio, Todos os domínios ou um domínio: aí a chave só envia com remetentes dele. |
Criar chaves só de envio ou restritas a um domínio, e o número de chaves, dependem do plano.
Dica
Use chaves só de envio em tudo que apenas dispara e-mails (checkout, WordPress, ERP) e uma chave por sistema: se uma vazar, você revoga só ela, sem derrubar o resto, e os logs mostram quem fez cada chamada.
Detalhe de uma chave
Clicar numa chave abre o resumo dela, com o botão Revogar:
| Parte | O que mostra |
|---|---|
| Permissão e Domínio | O que a chave pode e a que domínio está presa (ou Todos). |
| Total de usos e Último uso | O uso acumulado. |
| Criada por e Criada em | Quem criou e quando. |
| Requisições recentes | As últimas 10 chamadas da chave, com o link Ver todas para os Logs já filtrados por ela. Sem chamadas, aparece Nenhuma requisição registrada com esta chave. |
Atenção
Revogar uma chave é imediato e não tem volta. Troque a chave nos sistemas que a usam antes de revogar a antiga: crie a nova, atualize o sistema e só então revogue.
Veja também: Permissões (API) · Chaves de API (API).