Ir al contenido principal
Español— Elegir un idioma
Menú

Validación de la clave de gestión

Lección 13 de 14 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Verifica la integridad de tus claves
  2. Endpoint de validación
  3. Integración en tus scripts
  4. Auditoría de claves de inferencia
  5. Lista de comprobación de seguridad de claves
  6. Principio de separación de funciones
  7. Puntos clave

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:

TipoUsoQuién tiene acceso
Clave de gestiónAdministración, facturación, analíticasAdministradores de infraestructura
Clave de producciónLlamadas a API en producciónAplicación de producción
Clave de stagingPruebas en preproducciónEquipo de desarrollo
Clave de desarrolloDesarrollo localDesarrollador 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/validation comprueba 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)