Chaves de API

GET /keys lista cada chave que quem chama consegue ver, as mais recentes primeiro e uma página de cada vez, com o estado, os âmbitos, a função, o âmbito de envio, a última utilização e quem a criou e a alterou por último. GET /keys/{id} lê uma. Nenhuma leitura devolve alguma vez um segredo: maskedKey chega para distinguir duas chaves. Ambas precisam de keys:read.

{  "object": "api_key",  "id": "4c1b257a66287fd113bd89d0",  "name": "Billing sender",  "maskedKey": "oe_live_4c1b…kX7a",  "status": "active",  "scopes": ["emails:send"],  "roleId": null,  "domainAllowlist": ["billing.acme.com"],  "expiresAt": "2026-12-22T09:00:00.000Z",  "lastUsedAt": "2026-09-23T08:14:02.000Z",  "createdBy": { "kind": "apiKey", "name": "API key Provisioner", "label": "API key Provisioner" }}

• —POST /keys cria uma chave e devolve o seu segredo em token, uma única vez. Se omitidos, o âmbito é emails:send e a função, o âmbito de envio e a expiração são os de quem chama.
• —PATCH /keys/{id} muda o nome de uma chave, substitui os seus âmbitos ou o âmbito de envio e desativa-a e ativa-a com enabled. Desativar é a escolha reversível: a chave mantém tudo e é recusada com inactive_api_key até ser ativada de novo.
• —POST /keys/{id}/rotate dá a uma chave um segredo novo e devolve-o uma vez. O segredo antigo deixa de funcionar no instante em que a chamada regressa.
• —POST /keys/{id}/revoke retira uma chave para sempre, com um reason opcional. DELETE /keys/{id} remove-a depois da lista e mantém o seu histórico.
• —Todas precisam de keys:manage. Rodar a própria chave que chama também funciona com keys:write, exatamente como POST /keys/self/rotate.

Cada alteração é verificada contra a chave que a faz. Uma chave que ficaria fora de quem chama em qualquer eixo é recusada com 403 beyond_caller_authority, e param nomeia o eixo:

• —Âmbitos: só os que quem chama tem depois de a sua própria função os ter restringido.
• —Função: quem chama limitado por uma função só pode criar e gerir chaves limitadas pela mesma função.
• —Expiração: quem chama e expira só pode criar e gerir chaves que não expirem mais tarde.
• —Modo: uma chave de teste só alcança chaves de teste.
• —Âmbito de envio: só domínios e endereços dentro do de quem chama, e ter um endereço nunca cobre o seu domínio inteiro.

A consola pede-lhe que se verifique de novo antes de criar ou rodar uma chave. A uma chamada feita com uma chave não se pode pedir isso, por isso keys:manage é uma credencial que cria credenciais: uma chave divulgada que a tenha pode criar chaves suas, até ao seu próprio alcance, que continuam a funcionar depois de ela ser revogada.

• —Dê keys:manage apenas a uma automação cujo trabalho seja emitir chaves, nunca a uma chave que envia correio.
• —Restrinja essa chave: uma função, um âmbito de envio e uma expiração. Tudo o que ela cria herda os três e nunca os pode exceder.
• —Acompanhe GET /keys/activity. Cada chave que ela cria, altera ou revoga fica registada em seu nome, por isso uma fuga aparece como chaves que não esperava.
• —keys:read expõe o registo de pedidos, endereços IP e agentes do utilizador incluídos. Trate-o como acesso de auditoria.

GET /keys/requests e GET /keys/{id}/requests leem cada chamada autenticada que uma chave fez, as mais recentes primeiro: método, caminho, estado, código de erro, duração, IP e agente do utilizador, nunca um corpo nem uma query string. keyIds, failedOnly, since e until são os filtros que a consola oferece. GET /keys/activity e GET /keys/{id}/activity leem o que aconteceu às chaves, com actor a nomear quem o fez, como @username ou API key <name>. Nada é apagado, e uma chave eliminada mantém o seu histórico.