Validation de la clé management

Vérifier l’intégrité de vos clés

La validation des clés de gestion (management keys) est la première ligne de défense de votre infrastructure API. Avant toute opération critique — déploiement, rotation, modification de facturation — vérifiez que votre clé est valide et que ses permissions sont correctes.

Endpoint de validation

GET /auth/management-keys/validation

curl "https://management-api.x.ai/auth/management-keys/validation" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

La réponse confirme que la clé est active et retourne l’équipe, les permissions et les dates associées. Le champ à ne pas négliger est la date d’expiration : c’est la seule information qui vous permet d’anticiper une panne au lieu de la subir, puisqu’une clé expirée ne prévient pas — elle se contente de renvoyer 401 au premier appel qui suit.

Cas d’erreur

• 401 Unauthorized : la clé est invalide, expirée ou a été supprimée
• 403 Forbidden : la clé est valide mais n’a pas les permissions nécessaires pour l’opération demandée

Intégration dans vos scripts

Vérification au démarrage

Valider au démarrage déplace l’échec là où il coûte le moins. Sans cette vérification, une clé invalide se manifeste au premier appel utile — c’est-à-dire au milieu d’un traitement, parfois après plusieurs étapes déjà exécutées. Avec elle, le script s’arrête en trois secondes avec un message qui nomme la cause.

import requests
import sys

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."

def validate_management_key():
    """Vérifie que la clé de gestion est valide."""
    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("Clé de gestion valide")
            return True
        elif response.status_code == 401:
            print("ERREUR : clé de gestion invalide ou expirée")
            return False
        else:
            print(f"ERREUR : statut inattendu {response.status_code}")
            return False
    except requests.exceptions.RequestException as e:
        print(f"ERREUR de connexion : {e}")
        return False

if not validate_management_key():
    sys.exit(1)

Healthcheck périodique

Le healthcheck périodique couvre ce que la validation au démarrage laisse passer : les services de longue durée, démarrés il y a des semaines, dont la clé peut expirer ou être révoquée en cours de route. Une vérification horaire suffit — l’endpoint est léger et ne consomme aucun token d’inférence.

#!/bin/bash
# healthcheck-xai.sh — à exécuter toutes les heures via 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 "ALERTE : clé management xAI invalide (HTTP $STATUS)"
    # Envoyer une alerte (PagerDuty, Slack, email)
fi

Audit des clés d’inférence

L’audit périodique répond à trois questions qu’aucune alerte ne posera à votre place : quelles clés portent encore un wildcard, lesquelles n’ont aucune limite de débit, et lesquelles n’ont plus servi depuis des mois. Les deux premières sont des risques, la troisième une occasion de nettoyer — et les trois se traitent en une passe.

import requests
from datetime import datetime

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."

def audit_api_keys():
    """Audite toutes les clés API de l'équipe."""
    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"=== Audit des clés API — {datetime.now().strftime('%d/%m/%Y %H:%M')} ===")
    print(f"Nombre total de clés : {len(keys)}")

    for key in keys:
        name = key.get("name", "Sans nom")
        acls = key.get("acls", [])
        expire = key.get("expireTime", "Jamais")
        created = key.get("createdAt", "N/A")

        # Alertes
        warnings = []

        # Clé avec accès wildcard
        if "api-key:endpoint:*" in acls and "api-key:model:*" in acls:
            warnings.append("ACCÈS TOTAL (wildcards)")

        # Clé sans expiration
        if expire == "Jamais" or not expire:
            warnings.append("PAS D'EXPIRATION")

        # Clé sans limites de débit
        if not key.get("qps") and not key.get("qpm"):
            warnings.append("PAS DE LIMITES DE DÉBIT")

        status = " | ".join(warnings) if warnings else "OK"
        print(f"  [{name}] ACLs: {len(acls)} | Expire: {expire} | {status}")

audit_api_keys()

Checklist de sécurité des clés

Clés de gestion (management keys)

Les clés de gestion commandent tout le reste — leur compromission donne accès à la création, la modification et la suppression de toutes les clés d’inférence. Elles appellent donc le traitement le plus strict : stockage exclusif en coffre-fort, jamais en clair dans le code ni dans une configuration versionnée ; accès limité aux seuls administrateurs de l’infrastructure, pas aux développeurs applicatifs ; et une validation régulière via GET /auth/management-keys/validation, idéalement automatisée en healthcheck — une clé de gestion expirée découverte au moment où l’on en a besoin en urgence est le pire scénario opérationnel.

Clés d’inférence (API keys)

Pour les clés d’inférence, le principe directeur est l’isolation : chaque application reçoit sa propre clé, jamais de clé partagée entre services — sinon la rotation d’une clé compromise casse tous les services à la fois, et l’analytics ne permet plus d’attribuer la consommation. Chaque clé porte des ACLs restrictives calées sur son usage réel (pas de wildcard en production), des limites de débit dimensionnées sur le trafic attendu, et une date d’expiration quand l’usage est temporaire — un POC qui devait durer deux semaines n’a pas besoin d’une clé éternelle. L’audit régulier via le script présenté plus haut ferme la boucle : il révèle les clés oubliées, sur-privilégiées ou expirantes avant qu’elles ne deviennent des problèmes.

Principe de séparation des responsabilités

Maintenez une séparation claire entre les clés :

Chaque clé a un périmètre défini. Si un développeur quitte l’équipe, seule sa clé dev est supprimée — les autres restent intactes.

Points clés à retenir

• GET /auth/management-keys/validation vérifie la validité de votre clé de gestion
• Intégrez la validation au démarrage de vos scripts et dans votre monitoring
• Auditez régulièrement toutes les clés pour détecter les accès trop larges
• Séparez les clés par environnement et par responsabilité
• Alertez immédiatement en cas de clé invalide (expirée ou supprimée)