Documentation

Documentation

API de gestion

Une clé de gestion permet à vos propres systèmes de créer, grouper, limiter et révoquer les clés API de votre compte, et de lire via l’API ce qu’elles ont dépensé. Elle ne peut pas appeler de modèle.

À quoi elle sert

Certaines intégrations donnent à chacun de leurs clients, équipes ou utilisateurs une clé API propre, rangent les clés de chaque client dans un groupe, plafonnent ce qu’un groupe peut dépenser et relisent le coût par clé ou par groupe. Sur la page Clés API, cela convient pour quelques clés. Au-delà, une clé de gestion permet à un script ou à votre propre outil d’administration de faire la même chose via l’API.

Une clé de gestion est un identifiant différent d’une clé API. Elle n’est pas acceptée là où une clé API l’est : elle ne peut appeler ni /v1/chat/completions, ni /v1/messages, ni aucune autre route de modèle. Elle ne fonctionne que sur /v1/management/, où une clé API ne fonctionne pas.

Créer une clé de gestion

  • Ouvrez la page Clés API et allez tout en bas. Sous « Clés de gestion », choisissez « Nouvelle clé de gestion ». Le bloc reste replié tant que vous ne l’ouvrez pas.
  • Donnez un nom à la clé, par exemple « synchro facturation », pour que la page puisse indiquer quel programme a fait chaque modification.
  • Saisissez les adresses depuis lesquelles elle peut être appelée, une par ligne : une adresse seule comme 203.0.113.7, ou une plage comme 203.0.113.0/24. Sans liste d’autorisation, quiconque détient la clé peut l’utiliser, et la boîte de dialogue vous avertit si vous laissez la liste vide.
  • Copiez la clé quand elle s’affiche. Elle n’est affichée qu’une fois : Kunavo n’en conserve qu’un hachage.

Un compte peut avoir deux clés de gestion actives à la fois. Révoquez-en une pour faire place à une autre.

L’appeler

Envoyez la clé comme jeton Bearer à https://api.kunavo.com/v1/management. Les clés de gestion ne sont pas acceptées depuis un navigateur : leurs réponses n’ont pas d’en-têtes CORS, donc une page d’un autre site ne peut pas les appeler. Une clé doit rester sur votre serveur, jamais dans du code front-end.

curl https://api.kunavo.com/v1/management/groups \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"

Les réponses sont en JSON. Les erreurs ont la même forme que dans le reste de l’API : un objet error avec un message, un type, un code et, le cas échéant, le param en cause. Voici les statuts que vous rencontrerez :

StatutSignification
401La clé est absente, mal saisie ou révoquée, ou son compte est suspendu ou en cours d’examen.
403La clé a une liste d’autorisation IP et la requête provient d’une adresse qui n’y figure pas.
404Le groupe ou la clé n’existe pas, a été supprimé ou appartient à un autre compte. Les trois cas reçoivent la même réponse, si bien qu’un identifiant d’un autre compte ne révèle rien.
409La modification entre en conflit avec l’état du compte : un nom de groupe déjà utilisé, une clé révoquée, ou le compte à son plafond de 500 clés actives.
429Cette clé a fait 60 requêtes durant la dernière minute. L’en-tête Retry-After indique combien de secondes attendre.

Groupes

GET /v1/management/groups liste les groupes du compte, avec la limite mensuelle de chacun et le nombre de clés actives qu’il contient. POST en crée un, avec un monthly_limit_usd facultatif ; un nom déjà utilisé donne un 409. PATCH /v1/management/groups/{id} modifie le nom ou la limite : envoyez null pour aucune limite, et 0 pour suspendre toutes les clés du groupe sans en révoquer aucune. DELETE supprime un groupe, et ses appels gardent son nom sur la page Utilisation. Ses clés restent actives et n’ont plus de groupe, sauf si vous ajoutez ?revoke_keys=true, qui les révoque aussi.

curl https://api.kunavo.com/v1/management/groups \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CID000001", "monthly_limit_usd": 50}'

Clés

GET /v1/management/keys liste les clés, les plus récentes d’abord. Une page contient 50 clés, et limit porte ce nombre à 100. status vaut active par défaut, ou revoked ou all, et group_id restreint la liste à un groupe. Quand has_more est true, passez next_after comme after pour lire la page suivante. La clé en clair n’est jamais listée.

POST /v1/management/keys crée une clé avec un nom et, facultativement, un group_id, un monthly_limit_usd et un ip_allowlist. La réponse contient la clé en clair, une seule fois, dans son champ key. Un POST répété crée une seconde clé : avant de réessayer, listez donc les clés et cherchez son nom.

curl https://api.kunavo.com/v1/management/keys \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CID000001_user1", "group_id": "GROUP_ID", "monthly_limit_usd": 20}'

PATCH /v1/management/keys/{id} modifie le nom, le groupe, la limite ou la liste d’autorisation d’une clé ; un group_id valant null la sort de son groupe. DELETE la révoque. Révoquer une clé déjà révoquée n’est pas une erreur. Une clé révoquée ne peut plus être modifiée.

curl -X DELETE https://api.kunavo.com/v1/management/keys/KEY_ID \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"

Utilisation

GET /v1/management/usage renvoie l’utilisation de tout le compte sur 90 jours UTC au plus, comme GET /v1/usage le fait pour une seule clé. group_by accepte n’importe quelle combinaison de group, api_key, model et day, et vaut api_key par défaut. Les chiffres ont le même sens que sur la page Utilisation : un appel compte dans le groupe où se trouvait sa clé quand il a été passé, un appel en échec ne coûte rien, et le total d’une période égale au centime l’export CSV des mêmes jours. group_id et api_key_id restreignent le rapport à un groupe ou à une clé.

curl "https://api.kunavo.com/v1/management/usage?start_date=2026-10-01&end_date=2026-10-31&group_by=group,api_key" \
  -H "Authorization: Bearer $KUNAVO_MANAGEMENT_KEY"
Les dates sont des jours calendaires UTC, bornes incluses. Un end_date postérieur à aujourd’hui est lu comme aujourd’hui, et la réponse renvoie la date de fin utilisée.

La protéger

  • Définissez une liste d’autorisation. Une clé qui ne fonctionne que depuis les adresses de votre serveur ne vaut pas grand-chose pour qui la vole.
  • Conservez la clé dans un coffre de secrets sur le serveur qui exécute votre outil. Ne la mettez jamais dans un navigateur, une application mobile ou un dépôt.
  • Si elle fuite, révoquez-la en bas de la page Clés API, ou avec DELETE sur elle. La boîte de dialogue de révocation peut aussi révoquer les clés que cette clé a créées.
  • Chaque modification faite par la clé via l’API est listée sous « Clés de gestion » sur la page Clés API, avec son heure, l’adresse d’où elle vient et la clé qui l’a faite : les 50 dernières modifications. Les modifications faites à la main sur cette page ne sont pas listées.
  • Une clé cesse de fonctionner d’elle-même quand son compte est suspendu ou placé en cours d’examen, et quand elle est révoquée.

Une clé de gestion peut faire 60 requêtes par minute. Faites une requête par modification, et lisez une liste page par page plutôt que clé par clé.

Les groupes, leurs limites mensuelles et la façon de compter leurs chiffres sont expliqués sur la page Groupes de clés. Les chiffres d’utilisation sont les mêmes que sur la page Utilisation.