Lister et modifier vos clés — Management API : clés & facturation

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

Cet endpoint est le point de départ de tout audit d’accès, et c’est souvent la première fois qu’on découvre l’inventaire réel : des clés créées pour un test il y a huit mois, une clé au nom d’un collaborateur parti, deux clés de production dont personne ne sait laquelle sert. Listez avant de créer quoi que ce soit de nouveau — la clé dont vous avez besoin existe peut-être déjà.

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 ce qui rend l’audit tenable au-delà d’une dizaine de clés. Deux questions reviennent en pratique et se répondent d’une requête : qui peut appeler le modèle le plus cher, et quelles clés portent encore un wildcard. La seconde est la plus utile — un wildcard oublié en production est le défaut de configuration le plus fréquent, et le plus silencieux.

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

Modifier plutôt que recréer n’est pas qu’une commodité : la clé secrète reste la même, donc aucun déploiement n’est nécessaire. C’est ce qui permet d’ajuster des limites ou de restreindre des permissions sans interruption de service — et, en cas de suspicion, de réduire les droits d’une clé en quelques secondes pendant que vous préparez sa 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 '{
    "name": "prod-backend-v3",
    "acls": [
      "api-key:endpoint:chat",
      "api-key:endpoint:embed",
      "api-key:model:grok-4.20-0309-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

Voici le détail qui explique la moitié des « bugs » signalés après une modification de clé : le changement n’est pas instantané sur tous les serveurs. Une clé fraîchement créée peut répondre 401 pendant quelques instants, une ACL élargie peut ne pas être encore active — et l’on cherche l’erreur dans son propre code alors qu’il suffisait d’attendre. L’endpoint de propagation existe précisément pour lever ce doute :

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

Le passage en production est le scénario de modification le plus courant, et le réflexe de créer une clé neuve à cette occasion coûte cher : il faut la déployer partout, mettre à jour les coffres-forts, et l’ancienne traîne ensuite indéfiniment. Élever les limites de la clé existante évite tout cela.

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

En cas de suspicion, l’ordre des opérations compte. Restreindre d’abord — ACLs vidées, débit à zéro — arrête l’hémorragie en une requête, sans rien casser d’irréversible. La rotation vient ensuite, à froid, une fois que vous avez identifié où la clé était utilisée. L’inverse vous laisse avec une production à l’arrêt et une enquête à mener dans l’urgence.

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