Claves de API

GET /keys lista cada clave que quien llama puede ver, las más recientes primero y página a página, con su estado, ámbitos, rol, ámbito de envío, cuándo se usó por última vez y quién la creó y la cambió por última vez. GET /keys/{id} lee una. Ninguna lectura devuelve nunca un secreto: maskedKey basta para distinguir dos claves. Ambas necesitan 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 crea una clave y devuelve su secreto en token, una sola vez. Si se omiten, el ámbito es emails:send y el rol, el ámbito de envío y la caducidad son los de quien llama.
• —PATCH /keys/{id} cambia el nombre de una clave, sustituye sus ámbitos o su ámbito de envío y la desactiva y la vuelve a activar con enabled. Desactivar es la opción reversible: la clave lo conserva todo y se rechaza con inactive_api_key hasta que se vuelva a activar.
• —POST /keys/{id}/rotate da a una clave un secreto nuevo y lo devuelve una vez. El secreto anterior deja de funcionar en el instante en que vuelve la llamada.
• —POST /keys/{id}/revoke retira una clave para siempre, con un reason opcional. DELETE /keys/{id} la quita después de la lista y conserva su historial.
• —Todas necesitan keys:manage. Rotar la propia clave que llama también funciona con keys:write, exactamente como POST /keys/self/rotate.

Cada cambio se comprueba contra la clave que lo hace. Una clave que acabaría fuera de quien llama en cualquier eje se rechaza con 403 beyond_caller_authority, y param nombra el eje:

• —Ámbitos: solo ámbitos que tiene quien llama después de que su propio rol los haya acotado.
• —Rol: quien llama limitado por un rol solo puede crear y gestionar claves limitadas por el mismo rol.
• —Caducidad: quien llama y caduca solo puede crear y gestionar claves que no caduquen después.
• —Modo: una clave de prueba solo alcanza claves de prueba.
• —Ámbito de envío: solo dominios y direcciones dentro del de quien llama, y tener una dirección nunca cubre su dominio entero.

La consola te pide que vuelvas a verificarte antes de crear o rotar una clave. A una llamada hecha con una clave no se le puede pedir eso, así que keys:manage es una credencial que crea credenciales: una clave filtrada que la tenga puede crear claves propias, hasta su propio alcance, que siguen funcionando después de revocarla.

• —Da keys:manage solo a una automatización cuyo trabajo sea emitir claves, nunca a una clave que envía correo.
• —Acota esa clave: un rol, un ámbito de envío y una caducidad. Todo lo que crea hereda los tres y nunca puede superarlos.
• —Vigila GET /keys/activity. Cada clave que crea, cambia o revoca queda registrada a su nombre, así que una filtración aparece como claves que no esperabas.
• —keys:read expone el registro de solicitudes, direcciones IP y agentes de usuario incluidos. Trátalo como acceso de auditoría.

GET /keys/requests y GET /keys/{id}/requests leen cada llamada autenticada que hizo una clave, las más recientes primero: método, ruta, estado, código de error, duración, IP y agente de usuario, nunca un cuerpo ni una cadena de consulta. keyIds, failedOnly, since y until son los filtros que ofrece la consola. GET /keys/activity y GET /keys/{id}/activity leen lo que les pasó a las claves, con actor nombrando quién lo hizo, como @username o API key <name>. Nada se poda, y una clave eliminada conserva su historial.