Démarrage rapide

Suivez le Guide d’authentification pour vous connecter, puis ouvrez la page Clés de gestion et créez une clé de gestion. Stockez-la séparément des clés d’application standard. Envoyez-la en tant que jeton Bearer uniquement aux points de terminaison de gestion de la plateforme.

Une clé API standard ne peut pas appeler les points de terminaison de gestion des clés ou des garde-fous. Une clé de gestion valide peut tout de même recevoir 403 Forbidden si son propriétaire ne dispose plus du rôle de compte requis.

Utilisez GET /api/v1/keys pour inspecter les clés visibles par le compte de la clé de gestion :

Utilisez les identifiants publics retournés pour les requêtes ultérieures de récupération, de mise à jour, de révocation ou d’attribution de guardrails. Ne déduisez jamais les accès à partir d’un nom de clé ou d’un jeton masqué.

Créez une clé d’application avec POST /api/v1/keys. Le secret complet n’est retourné que dans la réponse de création ; persistez-le dans votre gestionnaire de secrets avant de supprimer cette réponse. La rotation doit créer un remplacement, le déployer dans l’application, vérifier le trafic, puis révoquer l’ancienne clé.

credit_limit_windows accepte toute combinaison de plafonds de dépenses glissants 1h, 1d et 7d. Si une fenêtre configurée est épuisée, les appels avec cette clé retournent 429 Too Many Requests jusqu’à ce que l’utilisation quitte la fenêtre. Envoyez un objet vide lors de la mise à jour d’une clé pour effacer tous les plafonds glissants.

Lorsqu’une requête de création omet tous les champs de plafond de dépenses et guardrail_id, la nouvelle clé utilise les paramètres de gouvernance par défaut de l’espace de travail. Des plafonds explicites, des fenêtres glissantes ou un guardrail remplacent ce choix par défaut. Envoyez credit_limit_cents: null pour créer un plafond natif illimité. Un montant fourni sans intervalle de réinitialisation reste un plafond à vie. Les mises à jour ne réappliquent jamais les paramètres par défaut de l’espace de travail, et leur modification ne change pas les clés existantes.

La création et la mise à jour acceptent tags, un tableau de chaînes key:value complètes. Les réponses de liste, récupération, création et mise à jour renvoient le tableau complet. PATCH remplace le tableau ; omettre tags le conserve. La clé doit compter 1–32 caractères et la valeur 1–64, avec exactement un deux-points et aucun espace blanc. Au plus 20 tags distincts sont autorisés, prédéfinis compris. Un format invalide ou des choix prédéfinis contradictoires renvoient 422 avec des erreurs de validation ; une valeur autre qu’un tableau ou un élément autre qu’une chaîne renvoie 400.

Exactement un tag de finalité est requis : usage:developer ou usage:service. La création via Management API ajoute usage:service si aucune finalité n’est fournie, y compris avec tags: []. La création dans le Dashboard et les mises à jour sans finalité utilisent usage:developer. Les clés existantes sont migrées en Developer. L’environnement est facultatif et accepte au plus un choix parmi env:production, env:staging ou env:dev (env:prod n’est pas accepté).

Le tableau de bord propose, à la création et à la modification, des raccourcis de finalité et d’environnement, des tags personnalisés et des suggestions issues uniquement des clés standard conservées dans l’espace de travail actuel. Les listes affichent les valeurs et le tag complet au survol. Les tags ne modifient ni le propriétaire, ni la visibilité, ni les permissions des clés. Ils peuvent associer une clé à un budget partagé par tag.

Les administrateurs de l’espace de travail définissent les tags obligatoires d’un membre dans Team, via le formulaire de budget du membre. Ce sont des tags personnalisés sensibles à la casse, comme team:growth. Les espaces de noms usage: et env: sont réservés. Un membre peut avoir au maximum 19 tags obligatoires, et chaque clé reste limitée à 20 tags au total.

Chaque nouvelle clé standard inclut automatiquement les tags obligatoires de son propriétaire dans cet espace de travail. La création combine les tags soumis et les tags obligatoires avant validation. Par exemple, si le membre doit avoir team:growth, une requête de création via la Management API avec tags: ["project:chatbot"] renvoie project:chatbot, team:growth et la valeur par défaut usage:service.

Un PATCH fournissant tags doit conserver tous les tags obligatoires. Supprimer un tag obligatoire renvoie 422 avec une erreur de validation nommant les tags manquants, même si l’appelant est administrateur. Omettre tags conserve les tags de la clé. Les membres peuvent toujours ajouter ou supprimer des tags ordinaires.

Pour supprimer un tag obligatoire, un administrateur modifie la configuration du membre dans Team. L’enregistrement ajoute les nouveaux tags obligatoires à toutes les clés standard existantes du membre et supprime les tags obligatoires révoqués. Les autres tags restent inchangés. Cela inclut les clés désactivées et expirées, mais exclut les clés supprimées. Si une clé ne peut pas accepter l’ensemble final de tags, tout l’enregistrement échoue et le formulaire indique la clé à corriger.

Les budgets par tag utilisent les tags actuels de chaque clé. Modifier les tags obligatoires modifie aussi l’attribution budgétaire des dépenses existantes pour la période en cours. Ajouter un tag obligatoire peut immédiatement épuiser son budget. Les membres existants commencent sans tags obligatoires et leurs clés restent inchangées jusqu’à ce qu’un administrateur enregistre une configuration.

Les guardrails sont des politiques de compte réutilisables pour les contrôles de modèle, de fournisseur et de dépenses. Gérez les politiques via /api/v1/guardrails, puis utilisez /api/v1/guardrail_assignments pour les attacher ou les supprimer. Traitez une assignation rejetée comme un échec de politique ou de propriété plutôt que de continuer silencieusement sans le guardrail.

Créez un garde-fou positif en mode block, puis affectez son guardrail_id et une tag sensible à la casse comme dept:ml. Choisissez exactement une cible, api_token_id, account_user_id ou tag. Les budgets partagés exigent un administrateur. Les budgets désactivés n’appliquent aucune limite. Les requêtes de gestion ne consomment pas de budget.

Les budgets regroupent les étiquettes actuelles des clés standard, y compris les dépenses des clés supprimées, désactivées et expirées. Ajouter ou retirer une étiquette déplace les dépenses de cette clé pour la période actuelle. Créer ou recréer un budget ne remet jamais les dépenses à zéro. Le nombre de clés exclut les clés supprimées. Chaque budget correspondant doit autoriser la requête ; un refus renvoie 403 et le nom de l’étiquette.

Un credit_limit_reset_interval nul signifie une limite à vie. Les autres périodes utilisent UTC. Le seuil d’alerte vaut 80 par défaut et accepte 1 à 100. Modifier directement un garde-fou affecte toutes ses affectations ; le tableau de bord copie d’abord la politique avant de modifier un budget par étiquette.

L’admission vérifie les réservations. Le règlement peut les dépasser, afficher une utilisation supérieure à 100% et bloquer les demandes payantes suivantes. Les journaux utilisent leur date de création ; les tâches en attente et les lots utilisent la leur. Une tâche acceptée pendant une période peut être réglée dans une période ultérieure.