Créer et configurer une clé API

Pourquoi créer des clés via l’API

Créer une clé à la main prend trente secondes, et c’est exactement ce qui rend l’automatisation nécessaire : ce qui est rapide se fait sans réfléchir, donc sans convention de nommage, sans limites de débit et avec un wildcard « pour aller vite ». Six mois plus tard, personne ne sait plus à quoi sert quelle clé.

Passer par l’API impose de nommer, de délimiter et de plafonner à chaque création, parce que ce sont des paramètres du script. La cohérence n’est plus une discipline à tenir mais une propriété du code. Vous pouvez automatiser la création de clés pour vos environnements (dev, staging, production), appliquer des ACLs granulaires et définir des limites de débit — le tout dans vos scripts de déploiement ou vos outils d’infrastructure.

Endpoint de création

Pour créer une clé API, envoyez une requête POST à l’endpoint suivant :

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

Corps de la requête

{
  "name": "ma-cle-production",
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 10,
  "qpm": 100,
  "tpm": 1000000,
  "expireTime": "2026-12-31T23:59:59Z"
}

Paramètres détaillés

name (obligatoire) : un identifiant lisible pour votre clé. Choisissez un nom descriptif qui indique l’usage (prod-backend, staging-chatbot, dev-john). Ce nom apparaît dans la console et dans les logs d’utilisation.

acls (obligatoire) : la liste des permissions accordées à cette clé. Deux formats sont disponibles :

• api-key:endpoint:[endpoint] — restreint les endpoints accessibles (chat, embed, image, models, sample, tokenize, documents)
• api-key:model:[model] — restreint les modèles utilisables (grok-4.20-0309-reasoning, grok-4.3, etc.)

Le caractère * sert de wildcard : api-key:endpoint:* autorise tous les endpoints, api-key:model:* tous les modèles. Réservez-le au développement local. En production, un wildcard signifie qu’une clé compromise donne accès à l’intégralité de ce que votre équipe peut faire — y compris les modèles les plus coûteux, que votre application n’utilise peut-être jamais.

qps (optionnel) : queries per second — nombre maximum de requêtes par seconde.

qpm (optionnel) : queries per minute — nombre maximum de requêtes par minute.

tpm (optionnel) : tokens per minute — nombre maximum de tokens traités par minute.

expireTime (optionnel) : date d’expiration au format ISO 8601. La clé sera automatiquement désactivée à cette date.

Exemple complet avec curl

curl -X POST "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-backend-v2",
    "acls": [
      "api-key:endpoint:chat",
      "api-key:endpoint:embed",
      "api-key:model:grok-4.20-0309-reasoning",
      "api-key:model:grok-4.3"
    ],
    "qps": 20,
    "qpm": 500,
    "tpm": 2000000,
    "expireTime": "2027-06-30T23:59:59Z"
  }'

La réponse contient la clé secrète, qui ne sera plus jamais affichée. Cette règle a une conséquence pratique à anticiper avant de lancer le script, pas après : si vous créez des clés en boucle, le stockage doit se faire dans le même mouvement. Une clé perdue entre sa création et son enregistrement n’est pas récupérable — il faut la supprimer et recommencer. Écrivez dans un coffre-fort (Vault, AWS Secrets Manager) plutôt que dans la sortie standard de votre terminal, où elle finira dans un historique.

Stratégies ACL recommandées

Clé de développement (large)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "qps": 5,
  "qpm": 50
}

Idéale pour le développement local : l’accès est large parce qu’on ne sait pas d’avance ce qu’on va essayer, mais les limites de débit restent basses. C’est le bon compromis — une boucle infinie écrite par erreur un vendredi soir coûtera quelques centimes au lieu de quelques centaines d’euros.

Clé de production (restreinte)

{
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 50,
  "qpm": 2000,
  "tpm": 5000000
}

En production, la règle s’inverse : on part de ce que l’application fait réellement et on n’autorise que cela. La question à se poser au moment de rédiger l’ACL est toujours la même — si cette clé fuite demain, qu’est-ce qu’un tiers peut en faire ? Une clé limitée au chat sur un seul modèle et plafonnée à dix requêtes par seconde donne une réponse courte.

Clé temporaire (expirable)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "expireTime": "2026-04-10T00:00:00Z"
}

L’expiration automatique règle le problème que personne ne traite : les clés qu’on oublie de supprimer. Un POC, une démonstration, un prestataire de passage — dans tous ces cas, expireTime garantit que l’accès s’éteint tout seul. C’est la seule façon fiable de tenir un inventaire propre, parce qu’elle ne repose sur la mémoire de personne.

Endpoints ACL disponibles

Pour connaître les endpoints que vous pouvez utiliser dans les ACLs, consultez :

GET /auth/teams/{teamId}/endpoints

Les endpoints disponibles sont : chat, embed, image, models, sample, tokenize, documents. Cette liste peut évoluer au fil du temps, donc vérifiez régulièrement.

Points clés à retenir

• La création de clé se fait via POST /auth/teams/{teamId}/api-keys
• Les ACLs suivent le format api-key:endpoint:[nom] ou api-key:model:[nom]
• Le wildcard * donne un accès complet à tous les endpoints ou modèles
• La clé secrète n’est affichée qu’une seule fois à la création — sauvegardez-la immédiatement
• Définissez toujours des limites de débit (qps, qpm, tpm) adaptées à l’usage
• Utilisez expireTime pour les clés temporaires