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

La rotation résout un problème que la suppression ne sait pas traiter : renouveler le secret sans perdre l’identité de la clé. Ses ACLs, ses limites de débit et son nom survivent à l’opération, ce qui veut dire qu’aucune configuration n’est à refaire — seul le secret change dans votre coffre-fort. C’est ce qui rend la rotation régulière praticable, là où recréer une clé imposerait de tout reconfigurer à chaque fois.

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é

Un point de cette procédure mérite d’être souligné parce qu’il surprend : l’ancien secret est invalidé immédiatement. Il n’existe pas de période de grâce pendant laquelle les deux secrets fonctionneraient. Vos services qui portent encore l’ancienne valeur échouent donc dès la seconde qui suit l’appel — d’où l’ordre des six étapes, et d’où l’intérêt de préparer le coffre-fort avant de déclencher la rotation, pas après.

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

Trois situations déclenchent une rotation, et elles n’ont pas la même urgence. La suspicion de fuite exige une rotation immédiate : un collaborateur avec accès aux clés quitte l’équipe, un log contenant une clé a été exposé publiquement, un dépôt Git contient une clé en clair — dans ces cas, chaque heure d’attente est une heure d’exposition, et la rotation se fait avant même l’analyse complète de l’incident. La rotation de politique, elle, est préventive : tous les 30, 60 ou 90 jours selon votre niveau d’exigence, elle borne la durée de vie d’une clé qui aurait fuité sans que personne ne s’en aperçoive. Le changement d’environnement, enfin — migration d’infrastructure, changement de prestataire — est l’occasion naturelle de repartir sur des clés propres plutôt que de transporter les anciennes dans un contexte qu’elles n’ont jamais connu.

Supprimer une clé

La suppression est permanente et irrévocable. La question à se poser avant de la lancer n’est pas « cette clé est-elle compromise ? » mais « ai-je encore besoin de ce périmètre d’accès ? ». Si la réponse est oui, c’est une rotation qu’il vous faut : elle neutralise le secret exposé tout en préservant la configuration. La suppression ne se justifie que pour une clé devenue inutile — un projet arrêté, un prestataire parti, un environnement démantelé.

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

Une rotation automatisée n’a de sens que si l’écriture dans le coffre-fort fait partie du même script, sans intervention manuelle entre les deux. Sinon vous déplacez simplement le risque : un secret généré par une machine et recopié à la main a plus de chances de finir dans un presse-papiers ou un historique de terminal qu’une clé créée depuis la console.

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