Créer et configurer une clé API

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

La console xAI permet de créer des clés manuellement, mais la Management API offre un contrôle programmatique complet. 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-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-reasoning, grok-4.20-mini, etc.)

Le caractère * sert de wildcard. Par exemple, api-key:endpoint:* autorise tous les endpoints, et api-key:model:* autorise tous les modèles.

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-reasoning",
      "api-key:model:grok-4.20-mini"
    ],
    "qps": 20,
    "qpm": 500,
    "tpm": 2000000,
    "expireTime": "2027-06-30T23:59:59Z"
  }'

La réponse contient la clé secrète (secret) qui ne sera plus jamais affichée. Stockez-la immédiatement dans un coffre-fort de secrets (Vault, AWS Secrets Manager, etc.).

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 : accès à tout, mais avec des limites basses pour éviter les coûts accidentels.

Clé de production (restreinte)

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

En production, limitez l’accès au strict nécessaire. Si votre application utilise uniquement le chat avec un modèle spécifique, ne donnez accès qu’à cela.

Clé temporaire (expirable)

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

Pour un test ou un POC, définissez une date d’expiration courte. La clé se désactivera automatiquement, sans intervention manuelle.

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