Lister et modifier vos clés

Inventaire de vos clés API

Au fil du temps, une équipe accumule des clés API pour différents environnements, projets et collaborateurs. La Management API permet de lister toutes les clés actives, de filtrer par permissions et de modifier leurs paramètres sans avoir à les recréer.

Lister les clés

L’endpoint GET /auth/teams/{teamId}/api-keys retourne la liste de toutes les clés de votre équipe :

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

Paramètres de requête

• pageSize : nombre de clés par page (par défaut, toutes les clés sont retournées)
• paginationToken : jeton pour récupérer la page suivante si le nombre de clés dépasse la taille de page
• aclFilters : filtrer les clés par permissions spécifiques

Filtrage par ACL

Vous pouvez ne récupérer que les clés ayant un certain niveau d’accès :

# Lister uniquement les clés ayant accès au chat
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Ce filtrage est utile pour auditer les accès : par exemple, identifier toutes les clés pouvant accéder à un modèle coûteux comme grok-4.20-reasoning.

Pagination

Pour les équipes avec de nombreuses clés, utilisez la pagination :

# Première page de 10 clés
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

# Page suivante avec le token reçu
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Modifier une clé existante

Pour mettre à jour les paramètres d’une clé sans la recréer, utilisez PUT /auth/api-keys/{api_key_id} :

curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-backend-v3",
    "acls": [
      "api-key:endpoint:chat",
      "api-key:endpoint:embed",
      "api-key:model:grok-4.20-reasoning"
    ],
    "qps": 30,
    "qpm": 1000,
    "tpm": 3000000
  }'

Ce que vous pouvez modifier

• name : renommer la clé pour refléter un changement d’usage
• acls : ajouter ou retirer des permissions (endpoints, modèles)
• qps / qpm / tpm : ajuster les limites de débit
• expireTime : prolonger ou raccourcir la durée de validité

Ce que vous ne pouvez pas modifier

• L’identifiant de la clé (api_key_id) reste fixe
• La clé secrète ne change pas lors d’une modification (pour cela, utilisez la rotation)
• L’équipe propriétaire ne peut pas être transférée

Vérifier la propagation

Après avoir créé ou modifié une clé, il peut y avoir un court délai avant que les changements soient effectifs sur tous les serveurs de xAI. Pour vérifier l’état de propagation :

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

Cet endpoint retourne le statut de propagation de la clé. Attendez que la propagation soit complète avant d’utiliser la clé en production, surtout après une modification des ACLs.

Scénarios courants

Upgrade d’une clé dev vers prod

Votre prototype fonctionne, vous passez en production. Plutôt que de créer une nouvelle clé, modifiez les limites :

curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-chatbot",
    "qps": 50,
    "qpm": 2000,
    "tpm": 5000000
  }'

Restreindre une clé compromise suspectée

Si vous suspectez une fuite, restreignez immédiatement les ACLs en attendant de faire la rotation :

curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "acls": [],
    "qps": 0,
    "qpm": 0
  }'

Points clés à retenir

• GET /auth/teams/{teamId}/api-keys liste toutes les clés avec pagination et filtrage ACL
• PUT /auth/api-keys/{apiKeyId} modifie les paramètres sans changer la clé secrète
• GET /auth/api-keys/{apiKeyId}/propagation vérifie que les changements sont effectifs
• Utilisez le filtrage ACL pour auditer régulièrement les accès de votre équipe
• Après toute modification, vérifiez la propagation avant d’utiliser la clé en production