Rotation des clés et cycle de vie

Pourquoi la rotation des clés est indispensable

Même si votre clé API n’a jamais été exposée, la rotation régulière est une pratique de sécurité fondamentale. Elle limite l’impact d’une compromission non détectée, satisfait les exigences d’audit SOC 2, et réduit la surface d’attaque temporelle.

La Management API de xAI fournit un endpoint dédié pour la rotation des clés sans interruption de service.

Rotation via la Management API

L’endpoint de rotation

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

Cet appel :

• Génère une nouvelle clé secrète pour l’identifiant existant
• Invalide définitivement l’ancienne clé secrète
• Conserve les ACLs, limites de débit et configurations existantes
• Le changement est immédiat et irréversible

Procédure de rotation sans interruption

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

1. Créez une nouvelle clé via POST /auth/teams/{teamId}/api-keys avec les mêmes permissions
2. Vérifiez la propagation : GET /auth/api-keys/{newKeyId}/propagation
3. Déployez la nouvelle clé sur vos backends
4. Testez que les appels fonctionnent avec la nouvelle clé
5. Désactivez l’ancienne clé ou attendez son expiration
6. Supprimez l’ancienne clé : DELETE /auth/api-keys/{oldKeyId}

Alternative : rotation in-place

Si vous préférez garder 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"

Attention : l’ancienne clé est invalidée immédiatement. Vos backends doivent être mis à jour dans la foulée.

Cycle de vie complet d’une clé API

Création

POST /auth/teams/{teamId}/api-keys

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

Surveillance

• GET /v1/api-key : vérifier le statut (api_key_blocked, api_key_disabled)
• Console xAI : monitoring de l’utilisation et des anomalies

Modification

PUT https://management-api.x.ai/auth/api-keys/{api_key_id}

Permet de mettre à jour le nom, les ACLs, les limites de débit et la date d’expiration.

Suppression

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

Permanent et irrévocable. Toute application utilisant cette clé cessera de fonctionner instantanément.

Stratégie de rotation automatisée

Rotation calendaire

Programmez la rotation à intervalle régulier :

• Mensuelle : pour les environnements hautement sensibles (finance, santé)
• Trimestrielle : pour les environnements professionnels standards
• Annuelle : minimum acceptable avec une date d’expiration définie

Rotation événementielle

Déclenchez une rotation immédiate dans ces cas :

• Départ d’un employé ayant accès aux clés
• Suspicion de compromission
• Incident de sécurité dans votre infrastructure
• Changement de prestataire ayant accès à vos systèmes

Mise en pratique : audit de vos clés

1. Listez toutes vos clés : GET /auth/teams/{teamId}/api-keys
2. Identifiez les clés sans expiration : ajoutez une expireTime
3. Vérifiez les ACLs : chaque clé a-t-elle les permissions minimales nécessaires ?
4. Supprimez les clés inutilisées : chaque clé active est un vecteur potentiel
5. Documentez : qui a accès à quelle clé et pourquoi

Points clés à retenir

• L’endpoint POST /auth/api-keys/{id}/rotate invalide définitivement l’ancienne clé
• Préférez la création d’une nouvelle clé puis suppression de l’ancienne pour éviter les interruptions
• Définissez toujours une date d’expiration sur vos clés
• Automatisez la rotation avec un script planifié
• Déclenchez une rotation immédiate lors de tout changement de personnel