Validación de la clave de gestión
En esta página
Verifica la integridad de tus claves
La validación de la clave de gestión es la primera línea de defensa de tu infraestructura de API. Antes de cualquier operación crítica —despliegue, rotación, cambios en la facturación—, verifica que tu clave sea válida y que sus permisos sean los correctos.
Endpoint de validación
GET /auth/management-keys/validation
curl "https://management-api.x.ai/auth/management-keys/validation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
La respuesta confirma que la clave está activa y devuelve el equipo, los permisos y las fechas asociadas. No pases por alto la fecha de caducidad: es la única información que te permite anticipar una interrupción en lugar de sufrirla, ya que una clave caducada no te avisa; simplemente devuelve un 401 en la primera llamada que se realice a continuación.
Casos de error
- 401 Unauthorized: La clave no es válida, ha caducado o ha sido eliminada.
- 403 Forbidden: La clave es válida, pero carece de los permisos necesarios para la operación solicitada.
Integración en tus scripts
Verificación al inicio
Validar al inicio traslada el fallo al punto donde menos cuesta. Sin esta comprobación, una clave no válida se manifiesta en la primera llamada útil; es decir, en mitad del procesamiento, a veces después de que varios pasos ya se hayan ejecutado. Con ella, el script se detiene en tres segundos con un mensaje que indica la causa.
import requests
import sys
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
def validate_management_key():
"""Comprueba que la clave de gestión sea válida."""
try:
response = requests.get(
f"{MANAGEMENT_API}/auth/management-keys/validation",
headers={"Authorization": f"Bearer {MGMT_KEY}"},
timeout=10
)
if response.status_code == 200:
print("Clave de gestión válida")
return True
elif response.status_code == 401:
print("ERROR: Clave de gestión no válida o caducada")
return False
else:
print(f"ERROR: Estado inesperado {response.status_code}")
return False
except requests.exceptions.RequestException as e:
print(f"ERROR DE CONEXIÓN: {e}")
return False
if not validate_management_key():
sys.exit(1)
Comprobación periódica del estado
La comprobación periódica del estado cubre lo que la validación inicial pasa por alto: servicios de larga duración, iniciados hace semanas, cuya clave puede caducar o ser revocada en el proceso. Una comprobación horaria es suficiente; el endpoint es ligero y no consume tokens de inferencia.
#!/bin/bash
# healthcheck-xai.sh — ejecutar cada hora mediante cron
STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
"https://management-api.x.ai/auth/management-keys/validation" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY")
if [ "$STATUS" != "200" ]; then
echo "ALERTA: Clave de gestión de xAI no válida (HTTP $STATUS)"
# Enviar una alerta (PagerDuty, Slack, correo electrónico)
fi
Auditoría de claves de inferencia
La auditoría periódica responde a tres preguntas que ninguna alerta hará por ti: qué claves siguen teniendo un comodín, cuáles no tienen límites de tasa y cuáles no se han usado en meses. Las dos primeras son riesgos; la tercera, una oportunidad para limpiar; y las tres se gestionan en una sola pasada.
import requests
from datetime import datetime
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
def audit_api_keys():
"""Audita todas las claves de API del equipo."""
response = requests.get(
f"{MANAGEMENT_API}/auth/teams/{TEAM_ID}/api-keys",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
keys = response.json().get("apiKeys", [])
print(f"=== Auditoría de claves de API — {datetime.now().strftime('%d/%m/%Y %H:%M')} ===")
print(f"Número total de claves: {len(keys)}")
for key in keys:
name = key.get("name", "Sin nombre")
acls = key.get("acls", [])
expire = key.get("expireTime", "Nunca")
created = key.get("createdAt", "N/D")
# Alertas
warnings = []
# Clave con acceso mediante comodín
if "api-key:endpoint:*" in acls and "api-key:model:*" in acls:
warnings.append("ACCESO TOTAL (comodines)")
# Clave sin caducidad
if expire == "Nunca" or not expire:
warnings.append("SIN CADUCIDAD")
# Clave sin límites de tasa
if not key.get("qps") and not key.get("qpm"):
warnings.append("SIN LÍMITES DE TASA")
status = " | ".join(warnings) if warnings else "OK"
print(f" [{name}] ACL: {len(acls)} | Caduca: {expire} | {status}")
audit_api_keys()
Lista de comprobación de seguridad de claves
Claves de gestión
Las claves de gestión controlan todo lo demás; su compromiso otorga acceso para crear, modificar y eliminar todas las claves de inferencia. Por tanto, exigen el manejo más estricto: almacenamiento exclusivo en una bóveda, nunca en texto plano en el código ni en la configuración versionada; acceso limitado únicamente a los administradores de infraestructura, no a los desarrolladores de aplicaciones; y validación regular mediante GET /auth/management-keys/validation, idealmente automatizada como una comprobación de estado. Descubrir una clave de gestión caducada cuando más la necesitas es el peor escenario operativo posible.
Claves de inferencia (claves de API)
Para las claves de inferencia, el principio rector es el aislamiento: cada aplicación recibe su propia clave, nunca una clave compartida entre servicios; de lo contrario, rotar una clave comprometida rompe todos los servicios a la vez y las analíticas ya no permiten atribuir el consumo. Cada clave lleva ACL restrictivas calibradas para su uso real (sin comodines en producción), límites de tasa dimensionados para el tráfico esperado y una fecha de caducidad cuando el uso es temporal; una prueba de concepto prevista para dos semanas no necesita una clave eterna. La auditoría regular mediante el script anterior cierra el ciclo: revela claves olvidadas, con privilegios excesivos o a punto de caducar antes de que se conviertan en problemas.
Principio de separación de funciones
Mantén una clara separación entre las claves:
| Tipo | Uso | Quién tiene acceso |
|---|---|---|
| Clave de gestión | Administración, facturación, analíticas | Administradores de infraestructura |
| Clave de producción | Llamadas a API en producción | Aplicación de producción |
| Clave de staging | Pruebas en preproducción | Equipo de desarrollo |
| Clave de desarrollo | Desarrollo local | Desarrollador individual |
Cada clave tiene un ámbito definido. Si un desarrollador abandona el equipo, solo se elimina su clave de desarrollo; las demás permanecen intactas.
Puntos clave
GET /auth/management-keys/validationcomprueba la validez de tu clave de gestión- Integra la validación en el inicio de tus scripts y en la monitorización
- Audita regularmente todas las claves para detectar accesos demasiado amplios
- Separa las claves por entorno y responsabilidad
- Alerta de inmediato ante una clave no válida (caducada o eliminada)