Autenticación
Un único tipo de credencial, y las maneras en que se rechaza una solicitud.
El encabezado
La URL base es api.openemail.uk. Cada solicitud lleva la clave en un encabezado Authorization.
Authorization: Bearer oe_live_9f2c1a4b7e05d3862c1f0a44_kX7…Aquí no autentica nada más. Tanto una cookie de sesión como un token de sesión se rechazan con invalid_credential_type, que nombra la credencial que hay que enviar en su lugar en vez de dejarte adivinar ante un 401 a secas.
Comprobar que una clave funciona
GET /ping es la prueba de humo: no necesita ningún ámbito y te dice qué es la clave.
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"}Si esto funciona y otra cosa devuelve 401, el problema es el ámbito, no la clave.
scopes es la lista EFECTIVA y la única que autoriza algo. grantedScopes es aquello con lo que se emitió la clave, y ambas difieren solo cuando un rol está limitando la clave. La página Ámbitos explica esa intersección. Un roleId con valor null significa que no hay techo, que es lo más amplio que llega a ser una clave.
Ver con qué direcciones puede enviar una clave
GET /addresses es la respuesta a un 403 que no esperabas.
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 tiene tres causas: la dirección está desactivada, el ámbito de envío de la clave la deja fuera (ni su dominio ni la dirección en sí están en la clave), o el dominio todavía no puede firmar. enabled en la dirección y sendingVerified en su dominio distinguen esos casos, y ahí está la mayor parte del tiempo de depuración que ahorra este endpoint. Un dominio puede estar verificado para recibir y aun así no poder enviar.
unrestricted: true significa que se acepta cualquier parte local de un dominio verificado, incluidas las que nadie ha creado todavía.
Cómo se rechaza una clave
| Código | Significa |
|---|---|
| missing_api_key | No hay ningún encabezado Authorization. |
| invalid_credential_type | Una cookie o un token de sesión. Envía una clave de API. |
| invalid_api_key | No es una clave que hayamos emitido, o el secreto no coincide. |
| revoked_api_key | Emitida aquí y luego revocada. Se distingue a propósito. Es la diferencia entre un arreglo de cinco minutos y una tarde entera. |
| expired_api_key | Emitida aquí y luego caducada. |
| insufficient_scope | Una clave real, sin el ámbito que necesita este endpoint. |
Revocar surte efecto en la siguiente llamada. La fila permanece después en la página de claves, así que todavía puedes saber si algo estaba usando la clave cuando la eliminaste. El estado más útil de esa pantalla es «nunca usada», porque es como se distingue una clave filtrada de una dependencia viva.
Rotar es la otra forma de retirar un secreto. Acuña un secreto nuevo para la misma clave, así que el id, el nombre, los ámbitos, el rol, el ámbito de envío y todas las filas de solicitudes y de actividad siguen ahí; solo cambia el secreto. El anterior deja de funcionar en el instante en que la rotación termina, sin ventana de solapamiento, y el reemplazo se muestra una sola vez. Desde la consola está en el mismo menú que Revocar y te pide volver a verificarte primero. Una clave que tenga keys:write también puede rotarse a sí misma con POST /keys/self/rotate, que es como una integración rota de forma programada sin que nadie abra la consola.