Base de conocimiento
Claves API
Una clave por tarea, limitada a los permisos y remitentes que necesita, con cada llamada registrada.
Detalles
- Se crean en Configuración → Claves API, en un espacio de trabajo que sea tuyo. El secreto se muestra una vez y todas las claves son oe_live_.
- Una clave solo tiene los permisos que elijas, y una nueva empieza con emails:send. También puede llevar un rol, que es un techo y no una segunda concesión: GET /ping devuelve los permisos que nombra la clave y los que le deja el rol, así que un 403 por un permiso que la clave tiene a la vista tiene una causa visible.
- El ámbito de envío admite hasta 25 dominios completos y 50 direcciones sueltas. Un dominio completo cubre también las direcciones que se le añadan después, y un remitente fuera de la lista se rechaza con un 403.
- Una caducidad opcional hace que una clave expire sola, hasta diez años vista.
- Rotar cambia solo el secreto: el id, los permisos, el ámbito de envío y el historial de peticiones continúan, y el secreto anterior deja de funcionar en cuanto se crea el nuevo. Una clave con keys:write puede rotarse a sí misma por la API. Revocar es una actualización y no un borrado, así que una llamada posterior recibe revoked_api_key.
- Cada llamada autenticada se registra con su método, ruta, estado, código de error, duración, IP y agente de usuario, nunca con cuerpo ni parámetros de consulta. La página de la clave lo muestra como Analíticas, Actividad y Peticiones, con las rutas más usadas, cuánto fallan y su latencia mediana, y las mismas vistas cubren varias claves a la vez. El registro se conserva, no se recorta.
- Todo lo que hace la página también está en la API y el SDK: GET /keys y GET /keys/{id} leen claves sin sus secretos, POST /keys crea una, PATCH /keys/{id} le cambia el nombre, cambia sus ámbitos o su ámbito de envío y la desactiva y la vuelve a activar, y rotate, revoke y delete hacen lo que dicen. El registro de solicitudes y la actividad se leen igual, de una clave o de todas, con los filtros de la página. Leer necesita keys:read y cada cambio necesita keys:manage, dos ámbitos que ninguna clave tiene a menos que alguien se los haya dado. El servidor MCP también lee el registro y la actividad, como listApiKeyRequests y listApiKeyActivity.
- Una clave nunca crea ni alcanza una clave más amplia que ella misma: sus ámbitos, su rol, su caducidad, su modo y su ámbito de envío tienen que quedar dentro de la clave que hace la llamada. La verificación adicional no puede aplicarse a una llamada hecha con una clave, así que keys:manage es una credencial que crea credenciales. Dala solo a una automatización que emite claves, con un rol, un ámbito de envío y una caducidad propios, y vigila la pestaña Actividad, donde todo lo que hace queda registrado a su nombre.
- Lo que falta: una clave no se puede atar a direcciones IP y no se puede crear una clave en modo de prueba.