URL de base et première requête

La Management API : un plan de contrôle séparé

L’API de gestion de xAI (Management API) est distincte de l’API d’inférence que vous utilisez pour envoyer des prompts à Grok. Elle sert à administrer vos ressources : créer et gérer des clés API, configurer la facturation, surveiller la consommation et contrôler les accès de votre équipe. Toute cette administration passe par une URL dédiée.

URL de base

Cette séparation n’est pas un détail d’implémentation : elle traduit une différence de nature entre les deux API. L’une consomme des tokens et fait travailler des modèles ; l’autre administre, facture et donne des droits. Les tenir sur deux domaines et deux jeux de clés garantit qu’une clé volée côté application ne permet jamais de créer d’autres clés ni de lire votre facturation.

https://management-api.x.ai

À ne pas confondre avec https://api.x.ai qui est l’URL pour les appels d’inférence (chat completions, embeddings, etc.). Toutes les requêtes de gestion — clés, facturation, analytics — passent par management-api.x.ai.

Authentification Management API

Le mécanisme d’authentification est identique — un token Bearer dans l’en-tête Authorization — mais la clé, elle, ne l’est pas. C’est la confusion la plus fréquente au démarrage, et elle produit un 401 parfaitement opaque : rien dans le message d’erreur n’indique que vous avez simplement présenté la bonne clé à la mauvaise API.

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

Cette requête de validation (GET /auth/management-keys/validation) vous permet de vérifier que votre clé de gestion est valide et active. C’est le point d’entrée le plus simple pour tester votre configuration.

Clé de gestion vs clé d’inférence

• Clé de gestion : donne accès aux endpoints de management-api.x.ai (administration, facturation, analytics)
• Clé d’inférence : donne accès aux endpoints de api.x.ai (chat, embeddings, images)

Les deux types de clés sont générés depuis la console xAI, mais leurs périmètres sont différents. Une clé d’inférence ne peut pas accéder aux endpoints de gestion, et inversement.

Structure des endpoints

Les endpoints de la Management API suivent une organisation logique :

• /auth/teams/{teamId}/api-keys — gestion des clés API
• /auth/api-keys/{apiKeyId} — opérations sur une clé spécifique
• /auth/teams/{teamId}/models — modèles accessibles
• /auth/teams/{teamId}/endpoints — endpoints ACL disponibles
• /v1/billing/teams/{teamId}/ — facturation et analytics

Le paramètre teamId est l’identifiant de votre équipe dans la console xAI, et il structure presque tous les endpoints. Chaque équipe possède ses propres clés, quotas et paramètres de facturation — ce qui en fait l’unité d’isolation naturelle : séparer deux projets en deux équipes sépare aussi leurs budgets et leurs accès, sans aucune configuration supplémentaire.

Votre première requête de gestion

Voici un exemple complet pour valider votre configuration :

# Définir votre clé de gestion
export MANAGEMENT_API_KEY="xai-mgmt-..."

# Valider la clé
curl -s https://management-api.x.ai/auth/management-keys/validation \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -m json.tool

Si la réponse contient les informations de votre équipe et de votre clé, votre configuration est fonctionnelle. En cas d’erreur 401, vérifiez que vous utilisez bien une clé de gestion (et non une clé d’inférence).

Points clés à retenir

• La Management API utilise https://management-api.x.ai, distincte de https://api.x.ai
• L’authentification se fait via un token Bearer dans l’en-tête Authorization
• Les clés de gestion et les clés d’inférence ont des périmètres séparés
• Le endpoint GET /auth/management-keys/validation permet de tester votre configuration
• Tous les endpoints de gestion sont organisés autour du teamId