Autenticação
Um tipo de credencial, e as formas como um pedido é recusado.
O cabeçalho
O URL base é localhost:2222. Todos os pedidos levam a chave num cabeçalho Authorization.
Authorization: Bearer oe_live_9f2c1a4b7e05d3862c1f0a44_kX7…Mais nada autentica aqui. Um cookie de sessão e um token de sessão são ambos recusados com invalid_credential_type, que nomeia a credencial a enviar em vez de o deixar a adivinhar perante um 401 seco.
Verificar se uma chave funciona
GET /ping é o teste de fumo: não precisa de âmbito nenhum e diz-lhe o que é a chave.
curl "$OE/ping" -H "$AUTH"{ "ok": true, "keyId": "4c1b257a66287fd113bd89d0", "mode": "live", "scopes": ["emails:send", "emails:read"], "roleId": null, "grantedScopes": ["emails:send", "emails:read"], "workspaceId": "10417196-e324-4283-af98-66ec62167c47"}Se isto funcionar e outra coisa devolver 401, o problema é o âmbito, não a chave.
scopes é a lista EFETIVA e a única que autoriza o que quer que seja. grantedScopes é aquilo com que a chave foi emitida, e as duas só divergem quando um papel está a limitar a chave. A página dos âmbitos explica essa interseção. Um roleId a null significa que não há teto, que é o mais amplo que uma chave chega a ser.
Ver em nome de quem uma chave pode enviar
GET /addresses é a resposta a um 403 que não estava à espera.
curl "$OE/addresses" -H "$AUTH"{ "object": "list", "unrestricted": false, "data": [ { "object": "address", "address": "[email protected]", "enabled": true, "canSend": true }, { "object": "address", "address": "[email protected]", "enabled": true, "canSend": false } ], "domains": [ { "domain": "acme.com", "receivingVerified": true, "sendingVerified": true, "catchAll": false } ]}canSend: false tem três causas: o endereço está desligado, o âmbito de envio da chave deixa-o de fora (nem o domínio dele nem o próprio endereço constam da chave), ou o domínio ainda não consegue assinar. enabled no endereço e sendingVerified no domínio distinguem os casos, e é aí que este endpoint poupa a maior parte do tempo de depuração. Um domínio pode estar verificado para receber e mesmo assim não conseguir enviar.
unrestricted: true significa que qualquer parte local num domínio verificado é aceite, incluindo as que ainda ninguém criou.
Como uma chave é recusada
| Código | Significa |
|---|---|
| missing_api_key | Nenhum cabeçalho Authorization. |
| invalid_credential_type | Um cookie ou um token de sessão. Envie uma chave de API. |
| invalid_api_key | Não é uma chave emitida por nós, ou o segredo não corresponde. |
| revoked_api_key | Emitida aqui e depois revogada. Distinta de propósito. É a diferença entre uma correção de cinco minutos e uma tarde inteira. |
| expired_api_key | Emitida aqui e entretanto expirada. |
| insufficient_scope | Uma chave verdadeira, sem o âmbito de que este endpoint precisa. |
A revogação produz efeito na chamada seguinte. A linha permanece na página de chaves depois disso, para que continue a poder perceber se alguma coisa estava a usar a chave quando a eliminou. O estado mais útil nesse ecrã é «nunca usada», porque é assim que se distingue uma chave divulgada de uma dependência viva.
Rodar é a outra forma de reformar um segredo. Cunha um segredo novo para a mesma chave, pelo que o id, o nome, os âmbitos, o papel, o âmbito de envio e todas as linhas de pedidos e de atividade se mantêm; muda apenas o segredo. O antigo deixa de funcionar no instante em que a rotação termina, sem janela de sobreposição, e o substituto é mostrado uma única vez. Na consola está no mesmo menu que Revogar e pede-lhe que se volte a verificar primeiro. Uma chave com keys:write também se pode rodar a si própria com POST /keys/self/rotate, que é como uma integração roda de forma agendada sem que ninguém abra a consola.