Skip to main content
Les clés API contrôlent qui et ce qui peut atteindre votre serveur d’observabilité Failproof AI, afin qu’un collecteur puisse envoyer des événements sans jamais obtenir de droits de lecture ou d’administration. Chaque clé porte une ou plusieurs permissions, et chaque permission conditionne l’accès à des routes spécifiques du serveur ; vous n’accordez que celles dont un service a besoin. La plupart des déploiements créent seulement trois types de clés.

Les 3 clés dont la plupart des déploiements ont besoin

Commencez ici. Ne consultez le catalogue complet des permissions ci-dessous que lorsque vous avez besoin d’une clé personnalisée à portée restreinte. Voir aussi Disposition recommandée des clés et Créer des clés.

Permissions

Le serveur applique un catalogue fixe de permissions ; chacune conditionne l’accès à des routes HTTP spécifiques. Une clé admin les possède toutes ; une clé à portée restreinte possède le sous-ensemble que vous accordez à la création. Les chaînes de permission inconnues sont rejetées lors de la création d’une clé.
Remarque : Deux permissions valides sont réservées aux humains/tableau de bord et ne peuvent pas être accordées à une clé API : orgs:admin (administration de l’instance, réservée aux opérateurs) et keys:update. Toute requête vers POST /keys ou PATCH /keys/:id qui tente d’accorder l’une ou l’autre est rejetée avec HTTP 422. Voir la ligne keys:update ci-dessous pour comprendre pourquoi une clé porteuse peut créer des clés mais jamais les modifier.

Ingestion et interrogation d’événements

Sessions et évaluations

Tableaux de bord

Requêtes enregistrées (compositeur SQL)

Assistant IA

Clés API

Utilisateurs du tableau de bord

Ces permissions alimentent la page Utilisateurs du tableau de bord, où les portées accordées à chaque membre s’affichent sous forme de puces : La page Utilisateurs : une carte par utilisateur du tableau de bord avec son e-mail, les permissions accordées et les contrôles de modification/désactivation

Paramètres opérationnels

La page Paramètres : paramètres opérationnels gérés par le tableau de bord tels que les connexions autorisées et les durées de vie des sessions/OTP, modifiables sans redémarrage

Alertes et incidents

Audits

Remarque : Pour donner à une clé l’accès à la surface d’audit, accordez-lui explicitement audits:*. Voir Notes de mise à jour et de compatibilité ascendante pour savoir comment les bénéficiaires existants ont été migrés lors du déploiement des Audits.
L’endpoint du sélecteur de destinataires GET /alerts/recipients (qui liste les e-mails des membres qu’un éditeur d’alertes peut notifier) est accessible par un détenteur de soit alerts:read soit alerts:write, de sorte que les éditeurs d’alertes peuvent remplir le sélecteur sans se voir accorder users:read.
Un lecteur de tableaux de bord a besoin des deux permissions dashboards:read (pour charger les vues enregistrées) et evaluations:read (les métriques de santé sont calculées à partir des données d’évaluation). Accordez dashboards:write pour permettre à un utilisateur de créer ou de modifier des tableaux de bord, et dashboards:delete pour les supprimer.
/health et /auth/* (demande OTP, vérification OTP, vérification de session, déconnexion) sont non authentifiés par conception ; il s’agit du flux de connexion et de la sonde de disponibilité. GET /access-granters nécessite une clé valide mais aucune permission spécifique, de sorte que tout utilisateur connecté peut voir quels administrateurs contacter pour les changements d’accès.

Ensembles de permissions

Les ensembles de permissions vous permettent d’appliquer un rôle nommé au lieu de sélectionner manuellement des tokens individuels à chaque fois. Plutôt que de sélectionner une douzaine de permissions une par une pour chaque nouvel utilisateur du tableau de bord ou clé API, vous choisissez un ensemble, et tous ceux qui y sont assignés bénéficient d’une attribution cohérente et vérifiable. La modification d’un ensemble personnalisé réapplique le nouvel accès à chaque utilisateur qui y est déjà assigné, de sorte qu’un changement de rôle est une seule modification plutôt qu’une mise à jour de chaque membre. Chaque organisation est initialisée avec trois ensembles intégrés : Les trois ensembles intégrés sont immuables ; leurs noms ont toujours la même signification, donc read-only, standard et admin peuvent être référencés en toute sécurité dans les politiques et l’onboarding. Un opérateur peut créer des ensembles personnalisés supplémentaires pour modéliser des rôles spécifiques à votre organisation (par exemple, un rôle « auteur de tableau de bord » ou un rôle « collecteur uniquement »). Les ensembles sont exposés dans le tableau de bord et gérés via l’API sur GET /permission-sets (liste, conditionnée par users:read) et POST /permission-sets / PUT /permission-sets/:name / DELETE /permission-sets/:name (créer, modifier, supprimer un ensemble personnalisé, conditionné par settings:write). La suppression ou la modification d’un ensemble intégré est refusée. L’appartenance à un ensemble est ce qui sous-tend deux autres fonctionnalités :
  • DEFAULT_USER_PERMISSIONS (l’accès présélectionné lorsqu’un administrateur ouvre + nouvel utilisateur) correspond par défaut à l’ensemble standard.
  • L’indicateur --set sur agenteye-orgctl (gestion des membres opérateurs) démarre un membre à partir d’un ensemble nommé, que vous affinez ensuite avec --add / --remove.
Remarque : Lorsqu’un ensemble inclut une permission non assignable à une clé (par exemple un ensemble personnalisé portant keys:update), l’initialisation d’une clé à partir de cet ensemble supprime les tokens non assignables ; le serveur rejetterait sinon la clé avec HTTP 422. Les utilisateurs du tableau de bord ne sont pas soumis à cette restriction.

Clé admin d’amorçage

La clé admin est l’unique identifiant racine qui permet à un opérateur de démarrer les accès depuis zéro : avec elle, vous pouvez créer toutes les autres clés à portée restreinte, inviter les premiers utilisateurs du tableau de bord et configurer l’instance avant qu’aucune autre clé n’existe. C’est la seule clé que vous ne créez pas via l’API des clés ; elle est provisionnée depuis l’environnement pour que le serveur soit accessible au premier démarrage. Définissez la variable d’environnement ADMIN_KEY sur le serveur. À chaque démarrage, le serveur insère ou met à jour cette valeur en tant que clé admin avec toutes les permissions. Pour la faire pivoter : modifiez ADMIN_KEY avec un nouveau secret et redémarrez le serveur.

Portée organisationnelle

Les organisations elles-mêmes sont créées et gérées hors bande par un opérateur, et non via cette API des clés. Le cycle de vie des organisations et des membres (créer / renommer / supprimer / purger une organisation ; ajouter / mettre à jour / supprimer un membre) se fait avec l’interface CLI agenteye-orgctl ; il n’existe ni API HTTP ni bouton de tableau de bord pour cela. Ce qui reste inchangé : les clés API par organisation sont toujours créées dans le tableau de bord (ou via cette API des clés) par les membres de l’organisation. Dans un déploiement multi-organisations, chaque clé créée par un membre d’une organisation (via cette API des clés ou la page Clés du tableau de bord) appartient à une seule organisation et ne peut lire ou écrire que les données de cette organisation ; l’organisation est inscrite dans la clé à la création et appliquée à chaque requête. Les deux clés d’amorçage constituent la seule exception : la clé admin (initialisée depuis ADMIN_KEY) et la clé dashboard-assistant (initialisée depuis AGENT_API_KEY) ont une portée d’instance (elles ne portent aucune organisation). Le tableau de bord s’authentifie avec la clé admin afin de pouvoir traiter les requêtes par organisation au nom des membres connectés. Les déploiements mono-tenant n’ont pas à se préoccuper de cela ; toutes les clés appartiennent à l’organisation default intégrée.

Créer des clés

Utilisez la clé admin (ou toute clé avec la permission keys:create) pour créer des clés supplémentaires à portée restreinte.

Clé collecteur (ingestion uniquement)

Clé tableau de bord (lecture seule)

Lorsque vous créez une clé via l’API HTTP, vous fournissez vous-même la valeur key ; choisissez un secret fort et stockez-le de manière sécurisée. (Le tableau de bord fonctionne différemment : il génère un secret fort pour vous et le montre une seule fois à la création ; voir Gestion des clés dans le tableau de bord.) La réponse confirme que la clé a été créée :

Lister les clés

Les secrets des clés ne sont pas retournés dans les réponses de liste, seulement les identifiants, noms et permissions.

Désactiver une clé

La désactivation révoque l’accès immédiatement sans supprimer l’enregistrement de la clé.

Régénérer une clé

Génère un nouveau secret pour une clé existante. L’ancien secret est invalidé immédiatement.
La réponse inclut le nouveau secret en clair, affiché une seule fois.

Gestion des clés dans le tableau de bord

La page Clés du tableau de bord fournit une interface utilisateur pour toutes les opérations ci-dessus. Vous avez besoin d’une clé avec la permission keys:read pour afficher la liste, et keys:create / keys:update / keys:disable / keys:regenerate pour les actions de création / modification / désactivation / régénération respectivement. La modification des permissions d’une clé (keys:update) est distincte de sa création (keys:create), ce qui vous permet d’accorder à un opérateur la possibilité de créer des clés sans pouvoir modifier la portée des clés existantes, ou inversement. La clé admin couvre tout cela. Lorsque vous créez une clé depuis le tableau de bord, vous ne fournissez pas le secret ; le tableau de bord génère un secret fort pour vous et l’affiche une seule fois à la création. Copiez-le immédiatement et stockez-le de manière sécurisée ; il ne sera plus jamais affiché, exactement comme lors d’une régénération. Vous pouvez toujours choisir les permissions de la clé directement, ou les initialiser depuis un ensemble de permissions (voir ci-dessous). La page Clés API : une carte par clé affichant son nom, les permissions accordées et la date de création, avec les actions de régénération et de désactivation ; les clés protégées comme admin sont marquées

Disposition recommandée des clés

Remarque : La clé de l’assistant est initialisée automatiquement par le serveur depuis la variable d’environnement AGENT_API_KEY (le même secret que l’agent présente comme AGENTEYE_API_KEY) ; il n’y a pas d’étape manuelle de création de clé ni de clé admin impliquée. Ses permissions sont figées dans le code source afin que la portée ne puisse pas être élargie par une mauvaise configuration : lecture sur les événements / évaluations / tableaux de bord, plus écriture sur les tableaux de bord et lecture / écriture / exécution des requêtes pour le flux de création « Demander à l’IA d’écrire une requête ». Tout SQL passe toujours par le même rôle en lecture seule et le même chemin SQL protégé qu’une requête écrite par un utilisateur, donc cela élargit la surface de création, pas la surface des données ; les opérations destructives (queries:delete, dashboards:delete) restent délibérément absentes de la clé de l’assistant. Comme la clé admin, elle est protégée : elle ne peut pas être désactivée ou régénérée via l’API des clés, seulement renouvelée en modifiant AGENT_API_KEY et en redémarrant. Les utilisateurs du tableau de bord ont en outre besoin de la permission agent:use pour voir et utiliser l’assistant. Si vous activez l’auto-instrumentation, donnez à l’assistant une clé séparée avec uniquement events:add.

Notes de mise à jour et de compatibilité ascendante

Ces notes ne sont nécessaires que si vous mettez à niveau une instance existante ; les nouveaux déploiements peuvent les ignorer.
Lors du déploiement des Audits, les bénéficiaires existants ont été élargis selon les mêmes formes de rôle que pour les alertes : chaque utilisateur et ensemble de permissions détenant alerts:read a obtenu audits:read, et chaque détenteur de alerts:write a obtenu audits:write. Les clés API existantes n’ont pas été élargies. Accordez explicitement audits:* à une clé si elle a besoin de la surface d’audit.
Les attributions stockées du token hérité alerts:ack sont interprétées comme incidents:ack afin que les équipes de permanence conservent leur accès sans devoir recréer leurs clés. Le token n’est plus assignable depuis l’éditeur d’utilisateurs du tableau de bord ; la matrice propose désormais incidents:ack à la place.

Étapes suivantes

  • SDK Python : comment votre code d’agent s’authentifie lors de l’envoi d’événements.
  • Sécurité : comment fonctionnent la connexion, le contrôle d’accès et l’isolation des données par organisation.