Rotation des clés et cycle de vie

Pourquoi la rotation des clés est indispensable

Une objection revient souvent en formation : « ma clé n’a jamais fuité, pourquoi la changer ? » La réponse tient en un mot : l’incertitude. Vous ne pouvez jamais prouver qu’une clé n’a pas été exposée — un log verbeux oublié sur un serveur, une capture d’écran partagée dans un ticket de support, un poste de développeur compromis six mois plus tôt. La rotation régulière transforme cette incertitude en risque borné : même si une clé a été copiée à votre insu, elle cessera de fonctionner à la prochaine rotation. C’est exactement le raisonnement que tiennent les auditeurs SOC 2, qui attendent une politique de rotation documentée, et c’est ce qu’on appelle réduire la surface d’attaque temporelle : plus une clé vit longtemps, plus la fenêtre d’exploitation d’une compromission silencieuse s’allonge.

La Management API de xAI a été conçue pour rendre cette pratique indolore : elle fournit un endpoint dédié qui permet de faire tourner une clé sans réécrire vos configurations.

Rotation via la Management API

L’endpoint de rotation s’appelle de façon très simple :

POST https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate

Comprenez bien ce que fait cet appel avant de l’utiliser : il génère une nouvelle clé secrète pour l’identifiant existant et invalide définitivement l’ancienne, tout en conservant les ACLs, les limites de débit et les configurations attachées à la clé. Le point qui surprend les équipes la première fois, c’est que le changement est immédiat et irréversible. Si votre backend de production utilise cette clé au moment où vous lancez la rotation, il commencera à recevoir des erreurs d’authentification dans la seconde. Il n’y a pas de période de grâce, pas de retour en arrière possible.

C’est pourquoi, en production, on préfère généralement une procédure en deux temps qui évite toute interruption. Vous créez d’abord une nouvelle clé via POST /auth/teams/{teamId}/api-keys, avec exactement les mêmes permissions que l’ancienne, puis vous vérifiez sa propagation avec GET /auth/api-keys/{newKeyId}/propagation — une clé fraîchement créée n’est pas instantanément connue de toute l’infrastructure, et déployer trop tôt produit des erreurs déroutantes. Vous déployez ensuite la nouvelle clé sur vos backends et vous testez que les appels fonctionnent réellement avec elle, pas seulement que le déploiement s’est terminé sans erreur. Ce n’est qu’une fois cette confirmation obtenue que vous désactivez l’ancienne clé, ou que vous la laissez atteindre son expiration, avant de la supprimer définitivement avec DELETE /auth/api-keys/{oldKeyId}.

Cette approche « nouvelle clé puis suppression » vous laisse une période de recouvrement pendant laquelle les deux clés coexistent : si le déploiement échoue sur un serveur, rien ne casse. La rotation in-place reste disponible si vous tenez à conserver le même identifiant de clé :

curl -X POST \
  "https://management-api.x.ai/auth/api-keys/key_abc123/rotate" \
  -H "Authorization: Bearer $MANAGEMENT_KEY"

Dans ce cas, prévoyez de mettre vos backends à jour dans la foulée, puisque l’ancienne clé meurt à l’instant même de l’appel.

Le cycle de vie complet d’une clé

Une clé bien gérée a une histoire en quatre actes. À la création, via POST /auth/teams/{teamId}/api-keys, vous définissez d’emblée son nom, ses ACLs et — c’est le réflexe à ancrer — sa date d’expiration :

{
  "name": "prod-chat-service",
  "acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
  "expireTime": "2026-12-31T23:59:59Z"
}

Une clé sans expireTime est une clé qui vivra éternellement si personne n’y pense ; une clé avec expiration force votre équipe à se poser la question de son renouvellement à date fixe. Vient ensuite la surveillance : GET /v1/api-key vous indique le statut de la clé (api_key_blocked, api_key_disabled), et la console xAI expose l’utilisation et les anomalies. Pour la modification en cours de vie — renommer, ajuster les ACLs, resserrer les limites de débit, repousser l’expiration — utilisez PUT https://management-api.x.ai/auth/api-keys/{api_key_id}. Enfin la suppression, DELETE /auth/api-keys/{apiKeyId}, est permanente et irrévocable : toute application qui utilisait cette clé cesse de fonctionner instantanément. Avant de supprimer, assurez-vous donc qu’aucun service oublié — un cron mensuel, un script de reporting — ne dépend encore d’elle.

Quelle stratégie de rotation adopter ?

La bonne fréquence dépend de la sensibilité de votre environnement. Une rotation mensuelle s’impose dans les contextes hautement sensibles comme la finance ou la santé, où la fenêtre d’exposition doit rester minimale. Une rotation trimestrielle convient aux environnements professionnels standards : assez fréquente pour être efficace, assez espacée pour ne pas peser sur les équipes. Une rotation annuelle, couplée à une date d’expiration définie, constitue le minimum acceptable — en dessous, votre politique de rotation n’en est plus une. Dans tous les cas, l’automatisation par script planifié vous évite de dépendre de la mémoire d’un administrateur.

À ce calendrier s’ajoute la rotation événementielle, déclenchée par les circonstances plutôt que par la date. Vous la déclencherez le plus souvent au départ d’un employé qui avait accès aux clés : même si la séparation est cordiale, la clé qu’il connaissait doit tourner le jour même — c’est une règle d’hygiène, pas une marque de défiance. Faites de même en cas de suspicion de compromission, d’incident de sécurité dans votre infrastructure, ou de changement de prestataire ayant eu accès à vos systèmes.

Vingt minutes pour reprendre la main sur votre parc

Le meilleur moment pour découvrir l’état réel de vos clés n’est pas le jour de l’audit. Listez donc dès maintenant toutes vos clés avec GET /auth/teams/{teamId}/api-keys et repérez celles qui n’ont pas d’expiration, pour leur ajouter une expireTime. Pour chacune, demandez-vous si ses ACLs correspondent au strict nécessaire de l’application qui l’utilise ; une clé créée pour un prototype et recyclée en production porte presque toujours trop de droits.

Supprimez ensuite les clés inutilisées, car chaque clé active est un vecteur d’attaque potentiel, et une clé dont personne ne se souvient est la pire de toutes : personne ne remarquera son usage anormal. Terminez en documentant qui a accès à quelle clé et pourquoi. C’est ce document, plus que les clés elles-mêmes, que vous ressortirez au prochain audit.

Points clés à retenir

• L’endpoint POST /auth/api-keys/{id}/rotate invalide définitivement l’ancienne clé, sans période de grâce
• En production, préférez la création d’une nouvelle clé puis suppression de l’ancienne pour éviter toute interruption
• Définissez toujours une date d’expiration sur vos clés
• Automatisez la rotation avec un script planifié (mensuel, trimestriel ou annuel selon la sensibilité)
• Déclenchez une rotation immédiate lors de tout changement de personnel ou incident de sécurité