Documentation API

Authentification et clés

Une clé par outil, deux plafonds par clé, une révocation immédiate. Comment obtenir une clé, comment la borner, et ce que vous recevez quand une borne est atteinte.

Deux en-têtes acceptés

La passerelle accepte la clé dans l'un ou l'autre de ces deux en-têtes. Les deux sont équivalents ; x-api-key existe pour les clients écrits pour l'API d'Anthropic, qui ne savent envoyer que celui-là.

En-têtes

Authorization: Bearer VOTRE_CLE_NETAIX

# ou, pour un client au format Anthropic :
x-api-key: VOTRE_CLE_NETAIX

Si les deux en-têtes sont présents, c'est x-api-key qui est lu.

Créer une clé

Les clés se créent dans l'application, jamais par l'API : une API qui peut émettre ses propres clés transforme une clé divulguée en accès permanent.

Connectez-vous sur app.netaix.fr.
Ouvrez la rubrique Connecteurs, puis le volet Pour les informaticiens.
Onglet Intégrations, bloc Jetons d'accès : bouton Générer.
Donnez à la clé un nom qui dit à quoi elle sert (par exemple Automatisation factures, Mon poste de travail).

Important

La clé n'est affichée qu'une seule fois, au moment de sa création. Elle ne peut pas être relue ensuite : seul son début reste visible, pour que vous puissiez reconnaître laquelle est laquelle. Si vous l'avez perdue, révoquez-la et créez-en une autre.

Deux points qui peuvent vous arrêter avant d'y arriver :

L'accès développeur doit être ouvert sur votre organisation. Sans lui, la création renvoie un refus. Pour un compte Développeur ouvert depuis la page Développeurs, c'est prévu dans le parcours ; sur une organisation existante, demandez-le nous.
La création demande votre mot de passe, et votre code à usage unique si vous avez activé la double authentification. Une session volée ne suffit donc pas à créer une clé. Chaque création déclenche un courriel d'alerte sur votre compte.

Deux plafonds par clé

Chaque clé porte son propre plafond de crédits, sur deux fenêtres. Ils protègent de ce qu'un plafond d'organisation ne voit pas : une clé divulguée, ou une boucle dans un agent, qui consommerait toute l'enveloppe sans jamais dépasser aucun seuil global.

Fenêtre	Défaut sur un compte Développeur	Remise à zéro
Jour	5 000 crédits	À minuit, heure universelle (UTC)
Cycle	20 000 crédits	Au début de chaque cycle de facturation

Ces défauts ne s'appliquent qu'aux comptes Développeur. Les clés d'un espace avec abonnement naissent sans plafond propre : l'enveloppe de l'abonnement les borne déjà.
Vous réglez ou retirez chaque plafond dans l'application. Le plus petit plafond réglable est de 100 crédits.
Une clé sans plafond propre reste bornée par l'enveloppe de son organisation.
Les plafonds comptent les appels payés en crédits Netaix. Si l'organisation utilise ses propres clés chez les fournisseurs de modèles, ces appels ne passent pas par les crédits et ne sont donc pas plafonnés ici.

Lire ses plafonds avec sa clé

Une clé peut connaître sa propre situation sans passer par l'application : GET /v1/netaix/usage rend, pour la clé qui appelle, le consommé, le plafond et le restant du jour et du cycle. C'est la façon d'afficher une jauge dans votre interface, ou de faire ralentir un traitement automatique avant qu'il se fasse refuser. Le détail des champs est dans la référence.

L'alerte à 80 %

Quand une clé atteint 80 % de l'un de ses plafonds, un courriel part vers son détenteur, une fois par fenêtre. Le seul geste proposé est de régler le plafond. Cette alerte existe pour qu'un plafond ne se découvre pas par une panne.

Ce que vous recevez au dépassement

Code HTTP	Code d'erreur	Ce que cela veut dire
`429`	`key_daily_quota_exceeded`	Le plafond du jour de cette clé est atteint. Il se libère à minuit UTC.
`429`	`key_quota_exceeded`	Le plafond de cycle de cette clé est atteint.
`429`	`quota_exceeded`	C'est l'enveloppe de l'organisation qui est épuisée, pas le plafond de la clé.
`402`	`topup_required`	Compte Développeur sans recharge payée : aucun appel n'est encore possible.
`402`	`insufficient_balance`	Compte Développeur dont le solde prépayé est épuisé. Rechargez pour reprendre.

À coder côté client

Ces trois 429 portent "type": "insufficient_quota". C'est ce que les bibliothèques officielles lisent comme un refus définitif : elles ne le réessaient pas, contrairement à un 429 de débit. Un réessai en boucle sur ces codes ne fera rien passer.

Révoquer

La révocation se fait dans le même écran, et elle est immédiate : l'appel suivant qui porte cette clé reçoit un 401. Révoquez sans hésiter, c'est le geste prévu, et créer une clé de remplacement prend quelques secondes.

Bonnes pratiques

Une clé par outil, par environnement et par projet. C'est ce qui rend une révocation indolore : vous coupez l'outil concerné, pas tous les autres. C'est aussi ce qui rend le relevé de consommation lisible, puisqu'il se ventile par clé.
Un plafond serré sur la clé d'un outil en recette. Un traitement par lot qui part en boucle coûte alors au plus le plafond du jour.
Jamais une clé dans un dépôt de code, un carnet de notes partagé ou une page web. Variable d'environnement, ou coffre de secrets.
Jamais une clé dans un code exécuté par le navigateur de vos utilisateurs. Tout ce qui part dans une page web est lisible. Appelez la passerelle depuis votre serveur.
Remplacez les clés à intervalle régulier, et à chaque départ d'une personne qui en détenait une.

Échecs d'authentification

Code	Cause
`401`	Tout refus de clé, sans distinction : aucun en-tête d'authentification, clé inconnue, révoquée, expirée, mal formée, ou dépourvue des droits nécessaires. Code `invalid_api_key`.
`429`	Trop d'échecs d'authentification consécutifs depuis la même origine. Code `too_many_auth_failures`, avec un en-tête `Retry-After`.

Un seul refus, volontairement

Ces refus sont indiscernables : même statut, même message, même code. Un refus qui dirait « expirée » ou « révoquée » confirmerait à qui essaie des clés au hasard que celle-ci a existé. Le motif réel est enregistré de notre côté : si vous êtes bloqué sans comprendre, écrivez-nous avec l'heure de l'appel et le début de la clé. Dans tous les cas, un 401 ne se réessaie pas, il se corrige ; un 429 après des échecs répétés se résout en attendant la durée indiquée par Retry-After.

← Démarrage rapide Modèles et routage →