Rotation et suppression de clés

La rotation : renouveler sans interrompre

La rotation de clé est une pratique de sécurité essentielle. Elle consiste à générer une nouvelle clé secrète pour remplacer l’ancienne, sans supprimer la clé elle-même. L’ancienne clé secrète est immédiatement et définitivement invalidée.

Effectuer une rotation

L’endpoint de rotation est :

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"

Comportement de la rotation

• L’ancienne clé secrète est immédiatement invalidée — toutes les requêtes l’utilisant échoueront avec une erreur 401
• Une nouvelle clé secrète est générée et retournée dans la réponse
• L’identifiant de la clé (apiKeyId), le nom, les ACLs et les limites de débit restent inchangés
• La nouvelle clé secrète n’est affichée qu’une seule fois — stockez-la immédiatement

Processus de rotation sécurisé

Pour éviter toute interruption de service, suivez cette procédure :

1. Préparez votre infrastructure pour accepter une nouvelle clé (variable d’environnement, coffre-fort)
2. Effectuez la rotation via l’API
3. Mettez à jour immédiatement le secret dans votre coffre-fort
4. Redéployez vos services avec la nouvelle clé
5. Vérifiez que les requêtes passent correctement avec la nouvelle clé
6. Vérifiez la propagation via GET /auth/api-keys/{apiKeyId}/propagation

Quand effectuer une rotation

• Suspicion de fuite : un collaborateur a quitté l’équipe, un log a été exposé publiquement, un dépôt Git contient une clé en clair
• Politique de sécurité : rotation régulière tous les 30, 60 ou 90 jours selon votre politique
• Changement d’environnement : migration d’infrastructure, changement de prestataire

Supprimer une clé

La suppression d’une clé est permanente et irrévocable. Contrairement à la rotation qui renouvelle la clé, la suppression élimine complètement la clé et toutes ses permissions.

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"

Conséquences de la suppression

• La clé et tous ses paramètres sont définitivement supprimés
• Toutes les requêtes utilisant cette clé échoueront immédiatement
• L’action est irréversible — il faudra créer une nouvelle clé avec de nouveaux paramètres
• L’historique d’utilisation de la clé reste disponible dans les analytics

Rotation vs suppression

Automatiser la rotation

Dans un environnement de production, automatisez la rotation avec un script :

import requests
import json

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

# Rotation
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")

# Stocker dans votre coffre-fort (exemple avec un fichier .env)
# En production, utilisez Vault, AWS Secrets Manager, etc.
print(f"Nouvelle clé générée. Mettez à jour votre coffre-fort.")

Rotation planifiée

Intégrez la rotation dans votre pipeline CI/CD ou dans un cron job :

# Exemple de cron : rotation le 1er de chaque mois à 3h du matin
0 3 1 * * /opt/scripts/rotate-xai-keys.sh

Points clés à retenir

• POST /auth/api-keys/{apiKeyId}/rotate invalide l’ancien secret et en génère un nouveau
• L’invalidation de l’ancien secret est immédiate et définitive
• DELETE /auth/api-keys/{apiKeyId} supprime la clé de manière irréversible
• Préférez la rotation à la suppression pour maintenir les ACLs et limites existantes
• Automatisez la rotation avec un script et un coffre-fort de secrets
• Vérifiez toujours la propagation après une rotation