Base de conhecimento

Chaves API

Uma chave por tarefa, limitada às permissões e remetentes de que precisa, com cada chamada registada.

Detalhes

Criadas em Definições → Chaves API, num espaço de trabalho que lhe pertença. O segredo é mostrado uma vez e todas as chaves são oe_live_.
Uma chave só tem as permissões que escolher, e uma nova começa com emails:send. Também pode ter uma função, que é um teto e não uma segunda concessão: GET /ping devolve as permissões que a chave indica e as que a função lhe deixa, por isso um 403 por uma permissão que a chave tem à vista tem uma causa visível.
O âmbito de envio admite até 25 domínios inteiros e 50 endereços soltos. Um domínio inteiro cobre também os endereços acrescentados depois, e um remetente fora da lista é recusado com um 403.
Uma validade opcional faz uma chave caducar sozinha, até dez anos à frente.
Rodar troca só o segredo: o id, as permissões, o âmbito de envio e o histórico de pedidos continuam, e o segredo antigo deixa de funcionar assim que o novo é criado. Uma chave com keys:write pode rodar-se a si própria pela API. Revogar é uma atualização e não uma eliminação, por isso uma chamada posterior recebe revoked_api_key.
Cada chamada autenticada é registada com o método, o caminho, o estado, o código de erro, a duração, o IP e o agente do utilizador, nunca com corpo nem parâmetros de consulta. A página da chave mostra-o como Análises, Atividade e Pedidos, com as rotas mais usadas, quantas vezes falham e a latência mediana, e as mesmas vistas cobrem várias chaves de uma vez. O registo é mantido, não aparado.
Tudo o que a página faz também está na API e no SDK: GET /keys e GET /keys/{id} leem chaves sem os seus segredos, POST /keys cria uma, PATCH /keys/{id} muda-lhe o nome, altera os seus âmbitos ou o âmbito de envio e desativa-a e volta a ativá-la, e rotate, revoke e delete fazem o que dizem. O registo de pedidos e a atividade leem-se da mesma forma, de uma chave ou de todas, com os filtros da página. Ler precisa de keys:read e cada alteração de keys:manage, dois âmbitos que nenhuma chave tem a menos que alguém lhos tenha dado. O servidor MCP também lê o registo e a atividade, como listApiKeyRequests e listApiKeyActivity.
Uma chave nunca cria nem alcança uma chave mais ampla do que ela própria: os seus âmbitos, a função, a expiração, o modo e o âmbito de envio têm todos de ficar dentro da chave que faz a chamada. A verificação adicional não se pode aplicar a uma chamada feita com uma chave, por isso keys:manage é uma credencial que cria credenciais. Dê-a apenas a uma automação que emite chaves, com função, âmbito de envio e expiração próprios, e acompanhe o separador Atividade, onde tudo o que faz fica registado em seu nome.
O que falta: uma chave não pode ser ligada a endereços IP, e não é possível criar uma chave em modo de teste.