Rotación y eliminación de claves
En esta página
Rotación: Renovar sin interrupciones
La rotación de claves es una práctica de seguridad crítica. Genera una nueva clave secreta para sustituir a la antigua sin eliminar la clave en sí. La clave secreta anterior queda invalidada de forma inmediata y permanente.
Realizar una rotación
La rotación resuelve un problema que la eliminación no puede abordar: renovar el secreto sin perder la identidad de la clave. Sus listas de control de acceso (ACL), límites de tasa y nombre sobreviven a la operación, por lo que no necesitas reconfigurar nada; solo cambia el secreto en tu bóveda de secretos. Esto hace que la rotación periódica sea práctica; recrear una clave exigiría reconfigurar todo cada vez.
POST /auth/api-keys/{apiKeyId}/rotate
curl -X POST "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/rotate" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Comportamiento de la rotación
- La clave secreta anterior queda invalidada inmediatamente; cualquier petición que la utilice fallará con un error 401
- Se genera y devuelve una nueva clave secreta en la respuesta
- El ID de la clave (
apiKeyId), el nombre, las ACL y los límites de tasa permanecen sin cambios - La nueva clave secreta se muestra una sola vez; guárdala de inmediato
Proceso de rotación seguro
Un aspecto de este procedimiento merece énfasis porque suele sorprender a los usuarios: la clave secreta anterior se invalida inmediatamente. No existe un periodo de gracia en el que funcionen ambos secretos. Cualquier servicio que siga utilizando el valor antiguo fallará al instante tras la llamada. Esto dicta el orden de los seis pasos siguientes: prepara tu bóveda de secretos antes de desencadenar la rotación, no después.
- Prepara tu infraestructura para aceptar una nueva clave (variable de entorno, bóveda)
- Realiza la rotación mediante la API
- Actualiza el secreto en tu bóveda inmediatamente
- Vuelve a desplegar tus servicios con la nueva clave
- Verifica que las peticiones se ejecutan correctamente con la nueva clave
- Verifica la propagación mediante
GET /auth/api-keys/{apiKeyId}/propagation
Cuándo rotar
Tres situaciones desencadenan una rotación, cada una con una urgencia distinta. Una fuga sospechada requiere una rotación inmediata: un miembro del equipo con acceso a la clave se marcha, se expone públicamente un registro que contiene una clave o un repositorio de Git incluye una clave en texto plano. En estos casos, cada hora de espera es una hora de exposición, así que rota antes de completar el análisis del incidente. La rotación basada en políticas es preventiva: cada 30, 60 o 90 días, según tus requisitos de seguridad, limita la vida útil de una clave que podría haberse filtrado sin que te dieras cuenta. Por último, los cambios de entorno —migración de infraestructura o cambio de proveedor— son una oportunidad natural para empezar de cero con claves limpias en lugar de arrastrar las antiguas a un contexto para el que no fueron diseñadas.
Eliminar una clave
La eliminación es permanente e irrevocable. La pregunta que debes hacerte antes de eliminar no es «¿Esta clave está comprometida?», sino «¿Sigo necesitando este ámbito de acceso?». Si la respuesta es sí, necesitas una rotación: neutraliza el secreto expuesto conservando la configuración. La eliminación solo está justificada para una clave que ya no es útil: un proyecto detenido, un proveedor que se ha marchado o un entorno dado de baja.
DELETE /auth/api-keys/{apiKeyId}
curl -X DELETE "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Consecuencias de la eliminación
- La clave y todos sus parámetros se eliminan permanentemente
- Todas las peticiones que utilicen esta clave fallarán inmediatamente
- La acción es irreversible; tendrás que crear una nueva clave con nuevos parámetros
- El historial de uso de la clave sigue disponible en las analíticas
Rotación frente a eliminación
| Aspecto | Rotación | Eliminación |
|---|---|---|
| La clave sigue existiendo | Sí | No |
| Se genera un nuevo secreto | Sí | No |
| ACL conservadas | Sí | No |
| Límites conservados | Sí | No |
| Reversible | No (se pierde el secreto antiguo) | No (se elimina la clave) |
| Uso típico | Renovación periódica | Clave obsoleta o compromiso confirmado |
Automatizar la rotación
La rotación automatizada solo tiene sentido si la escritura en la bóveda de secretos forma parte del mismo guion, sin intervención manual entre medias. De lo contrario, simplemente desplazas el riesgo: un secreto generado por máquina y copiado a mano tiene más probabilidades de acabar en el portapapeles o en el historial del terminal que una clave creada desde la consola.
import requests
import json
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
KEY_ID = "key-123"
# Rotar
response = requests.post(
f"{MANAGEMENT_API}/auth/api-keys/{KEY_ID}/rotate",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
new_key = response.json()
new_secret = new_key.get("secret")
# Guardar en tu bóveda (ejemplo con un archivo .env)
# En producción, usa Vault, AWS Secrets Manager, etc.
print(f"Nueva clave generada. Actualiza tu bóveda.")
Rotación programada
Integra la rotación en tu canalización de CI/CD o en una tarea cron:
# Ejemplo de Cron: rotación el día 1 de cada mes a las 3:00
0 3 1 * * /opt/scripts/rotate-xai-keys.sh
Puntos clave
POST /auth/api-keys/{apiKeyId}/rotateinvalida el secreto antiguo y genera uno nuevo- La invalidación del secreto antiguo es inmediata y permanente
DELETE /auth/api-keys/{apiKeyId}elimina la clave de forma irreversible- Prefiere la rotación a la eliminación para mantener las ACL y los límites existentes
- Automatiza la rotación con un guion y una bóveda de secretos
- Verifica siempre la propagación después de una rotación