Rotación de claves y ciclo de vida
En esta página
Por qué es esencial la rotación de claves
Una objeción habitual en las sesiones de formación es: «Mi clave nunca se ha filtrado, ¿por qué cambiarla?». La respuesta se resume en una palabra: incertidumbre. Nunca puedes demostrar que una clave no haya quedado expuesta: un registro verboso olvidado en un servidor, una captura de pantalla compartida en un ticket de soporte o una estación de trabajo de desarrollador comprometida hace seis meses. La rotación periódica convierte esta incertidumbre en un riesgo acotado: aunque alguien haya copiado una clave sin que lo sepas, dejará de funcionar en la siguiente rotación. Este es exactamente el razonamiento que siguen los auditores de SOC 2; esperan una política de rotación documentada. A esto lo llamamos reducir la superficie de ataque temporal: cuanto más tiempo viva una clave, mayor será la ventana de explotación ante un compromiso silencioso.
La API de gestión de xAI está diseñada para hacer que esta práctica sea indolora: proporciona un endpoint dedicado que te permite rotar una clave sin tener que reescribir tus configuraciones.
Rotación mediante la API de gestión
El endpoint de rotación es sencillo:
POST https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate
Asegúrate de entender qué hace esta llamada antes de usarla: genera una nueva clave secreta para el ID existente e invalida permanentemente la anterior, manteniendo las ACL, los límites de tasa y las configuraciones asociadas a la clave. Lo que suele pillar desprevenidos a los equipos la primera vez es que el cambio es inmediato e irreversible. Si tu backend de producción está usando esta clave cuando activas la rotación, comenzará a recibir errores de autenticación en cuestión de segundos. No hay periodo de gracia ni forma de revertir el proceso.
Por eso, en producción, generalmente prefieres un procedimiento de dos pasos para evitar cualquier interrupción. Primero, crea una nueva clave mediante POST /auth/teams/{teamId}/api-keys, con exactamente los mismos permisos que la antigua. A continuación, verifica su propagación con GET /auth/api-keys/{newKeyId}/propagation: una clave recién creada no se conoce instantáneamente en toda la infraestructura, y desplegarla demasiado pronto genera errores confusos. Después, despliega la nueva clave en tus backends y comprueba que las llamadas funcionan realmente con ella, no solo que el despliegue ha terminado sin errores. Solo cuando tengas esta confirmación deberías desactivar la clave antigua, o dejar que llegue a su fecha de caducidad, antes de eliminarla permanentemente con DELETE /auth/api-keys/{oldKeyId}.
Este enfoque de «nueva clave y luego borrar» te ofrece un periodo de solapamiento donde ambas claves coexisten: si el despliegue falla en un servidor, nada se rompe. La rotación in situ sigue disponible si quieres mantener el mismo ID de clave:
curl -X POST \
"https://management-api.x.ai/auth/api-keys/key_abc123/rotate" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
En este caso, planifica actualizar tus backends de inmediato, ya que la clave antigua deja de funcionar en el instante en que finaliza la llamada.
El ciclo de vida completo de una clave
Una clave bien gestionada tiene una historia de cuatro actos. En la creación, mediante POST /auth/teams/{teamId}/api-keys, defines su nombre, sus ACL y, este es el hábito que debes consolidar, su fecha de caducidad:
{
"name": "prod-chat-service",
"acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
"expireTime": "2026-12-31T23:59:59Z"
}
Una clave sin expireTime es una clave que vivirá para siempre si nadie piensa en ella; una clave con caducidad obliga a tu equipo a plantearse la renovación en una fecha fija. A continuación viene la monitorización: GET /v1/api-key te indica el estado de la clave (api_key_blocked, api_key_disabled), y la consola de xAI muestra el uso y las anomalías. Para modificaciones a mitad de vida —cambiar el nombre, ajustar las ACL, endurecer los límites de tasa, posponer la caducidad— usa PUT https://management-api.x.ai/auth/api-keys/{api_key_id}. Finalmente, la eliminación, DELETE /auth/api-keys/{apiKeyId}, es permanente e irreversible: cualquier aplicación que use esta clave dejará de funcionar al instante. Antes de borrarla, asegúrate de que ningún servicio olvidado —un cron mensual, un script de informes— dependa todavía de ella.
¿Qué estrategia de rotación deberías adoptar?
La frecuencia adecuada depende de la sensibilidad de tu entorno. La rotación mensual es obligatoria en contextos de alta sensibilidad como las finanzas o la sanidad, donde la ventana de exposición debe mantenerse mínima. La rotación trimestral es adecuada para entornos profesionales estándar: lo suficientemente frecuente para ser eficaz y lo suficientemente espaciada para no sobrecargar a los equipos. La rotación anual, junto con una fecha de caducidad definida, es el mínimo aceptable; por debajo de eso, tu política de rotación no es realmente una política. En todos los casos, la automatización mediante un script programado te evita depender de la memoria de un administrador.
A este calendario se suma la rotación impulsada por eventos, activada por circunstancias y no por fechas. Lo más habitual es activarla ante la salida de un empleado que tenía acceso a las claves: aunque la separación sea cordial, la clave que conocía debe rotar ese mismo día; esta es una norma de higiene de seguridad, no un signo de desconfianza. Haz lo mismo en caso de sospecha de compromiso, un incidente de seguridad en tu infraestructura o un cambio de proveedor que tuviera acceso a tus sistemas.
Veinte minutos para recuperar el control de tu inventario
El mejor momento para descubrir el estado real de tus claves no es el día de la auditoría. Así que lista ahora todas tus claves con GET /auth/teams/{teamId}/api-keys e identifica aquellas sin caducidad para añadirles un expireTime. Para cada una, pregúntate si sus ACL coinciden con el mínimo estricto requerido por la aplicación que la usa; una clave creada para un prototipo y reciclada en producción casi siempre arrastra demasiados derechos.
Luego elimina las claves no utilizadas, porque cada clave activa es un vector de ataque potencial, y una clave que nadie recuerda es la peor de todas: nadie notará su uso anómalo. Termina documentando quién tiene acceso a qué clave y por qué. Este documento, más que las propias claves, es lo que sacarás en la siguiente auditoría.
Puntos clave
- El endpoint
POST /auth/api-keys/{id}/rotateinvalida la clave antigua permanentemente, sin periodo de gracia - En producción, prefiere crear una nueva clave y luego borrar la antigua para evitar interrupciones
- Establece siempre una fecha de caducidad en tus claves
- Automatiza la rotación con un script programado (mensual, trimestral o anual según la sensibilidad)
- Activa la rotación inmediata ante cualquier cambio de personal o incidente de seguridad