Clés API

AgentEye utilise des clés API à granularité fine pour contrôler l’accès au serveur. Chaque clé est associée à une ou plusieurs permissions qui déterminent ses capacités.

Permissions

Le serveur applique un catalogue fixe de permissions ; chacune contrôle des routes HTTP spécifiques. Une clé admin les possède toutes ; une clé à portée limitée ne possède que le sous-ensemble que vous accordez lors de sa création. Les chaînes de permission inconnues sont rejetées lors de la création d’une clé.

Non assignables aux clés. Deux permissions valides sont réservées aux humains/au tableau de bord et ne peuvent pas être accordées à une clé API : orgs:admin (administration de l’instance, réservée à l’opérateur) et keys:update. Toute requête POST /keys ou PATCH /keys/:id tentant 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 des événements

Permission	Routes HTTP	Ce qu’elle autorise
`events:add`	`POST /events`	Ingérer des lots d’événements depuis un collecteur. C’est la seule permission dont un collecteur a besoin.
`events:read`	`GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export`	Interroger les événements, lister les environnements connus, lister les identifiants de modèles présents dans les données (utilisés par la vue Modèles et les filtres de modèles), calculer l’agrégat de latence qui alimente la carte thermique / la bande de percentiles, et exporter une session en JSONL. Les endpoints de facettes de la barre de filtres partagée `GET /events/environments` et `GET /events/models` sont accessibles avec soit `events:read` soit `evaluations:read`, de sorte que la page des sessions (contrôlée par `evaluations:read`) réutilise la même facette par organisation.

Sessions et évaluations

Permission	Routes HTTP	Ce qu’elle autorise
`evaluations:read`	`GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs`	Lister les sessions, lire les résultats d’évaluation, le bilan d’intégrité des évaluations agrégé utilisé par les tableaux de bord, et l’état de la file d’attente du worker d’évaluation.
`evaluations:trigger`	`POST /sessions/:session_id/re-evaluate`	Mettre manuellement en file d’attente une réévaluation pour une session terminée.

Tableaux de bord

Permission	Routes HTTP	Ce qu’elle autorise
`dashboards:read`	`GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles`	Lister les tableaux de bord, en charger un et lire ses tuiles.
`dashboards:write`	`POST /dashboards`, `PUT /dashboards/:id`, `POST /dashboards/:id/tiles`, `PUT /dashboards/:id/tiles/:tile_id`, `DELETE /dashboards/:id/tiles/:tile_id`, `PUT /dashboards/:id/tiles/layout`	Créer et modifier des tableaux de bord, ajouter / modifier / supprimer des tuiles, et réorganiser la grille de tuiles.
`dashboards:delete`	`DELETE /dashboards/:id`	Supprimer un tableau de bord entier (la suppression au niveau des tuiles relève de `dashboards:write`).

Requêtes sauvegardées (compositeur SQL)

Permission	Routes HTTP	Ce qu’elle autorise
`queries:read`	`GET /queries`, `GET /queries/:id`, `GET /queries/schema`	Lister les requêtes sauvegardées, en charger une et inspecter le schéma ClickHouse en lecture seule que le compositeur cible.
`queries:write`	`POST /queries`, `PUT /queries/:id`	Créer et modifier des requêtes sauvegardées. Le SQL est toujours acheminé via le même rôle en lecture seule et les mêmes vérifications `sql_guard` qu’un appel `queries:run`.
`queries:delete`	`DELETE /queries/:id`	Supprimer une requête sauvegardée.
`queries:run`	`POST /queries/run`	Exécuter du SQL sauvegardé ou ad hoc contre le rôle en lecture seule utilisé par le compositeur.

Assistant IA

Permission	Routes HTTP	Ce qu’elle autorise
`agent:use`	`GET /agent/conversations`, `POST /agent/conversations`, `GET /agent/conversations/:id`, `PATCH /agent/conversations/:id`, `DELETE /agent/conversations/:id`, `PUT /agent/conversations/:id/messages`	Interagir avec l’assistant IA du tableau de bord et gérer ses propres conversations (privées). Requis pour que l’utilisateur voie le panneau de l’assistant ; la clé propre à l’assistant est `dashboard-assistant` et est initialisée séparément (voir ci-dessous).

Permission	Routes HTTP	Ce qu’elle autorise
`keys:create`	`POST /keys`	Créer une nouvelle clé API à portée limitée. N’accorde pas la modification des permissions d’une clé existante (c’est `keys:update`).
`keys:read`	`GET /keys`	Lister les clés existantes. Les secrets ne sont jamais retournés par cet endpoint.
`keys:update`	`PATCH /keys/:id`	Modifier les permissions d’une clé existante. Permission réservée aux humains/au tableau de bord ; elle ne peut pas être assignée à une clé API (une clé porteuse peut créer des clés mais jamais les modifier).
`keys:disable`	`POST /keys/:id/disable`	Révoquer une clé. Les clés protégées (`admin`, `dashboard-assistant`) ne peuvent pas être désactivées ; effectuez leur rotation via la variable d’environnement + redémarrage.
`keys:regenerate`	`POST /keys/:id/regenerate`	Faire tourner le secret d’une clé. Les clés protégées ne peuvent pas être régénérées via cette route.

Utilisateurs du tableau de bord

Permission	Routes HTTP	Ce qu’elle autorise
`users:create`	`POST /users`, `GET /users/defaults`	Inviter un nouvel utilisateur du tableau de bord (envoie un e-mail + connexion OTP) et lire l’ensemble de permissions par défaut configuré dans le tableau de bord, utilisé pour pré-remplir le formulaire d’invitation.
`users:read`	`GET /users`, `GET /users/:id`	Lister les utilisateurs et charger un enregistrement d’utilisateur unique.
`users:update`	`PUT /users/:id`	Modifier les permissions d’un utilisateur. Les mises à jour envoient un e-mail de notification de changement de permissions à l’utilisateur concerné et prennent effet à sa prochaine requête ; aucune reconnexion n’est requise.
`users:delete`	`DELETE /users/:id`, `POST /users/:id/enable`	Désactiver un utilisateur (révoque ses sessions immédiatement) et réactiver un utilisateur précédemment désactivé.

Ces permissions alimentent la page Utilisateurs du tableau de bord, où les scopes accordés à chaque membre sont affichés 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

Permission	Routes HTTP	Ce qu’elle autorise
`settings:read`	`GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve`	Consulter les paramètres opérationnels gérés par le tableau de bord et leurs métadonnées ; lister les surcharges de fenêtre de contexte par modèle ; et résoudre la fenêtre effective pour un modèle.
`settings:write`	`PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows`	Modifier les paramètres opérationnels et ajouter, modifier ou supprimer des surcharges de fenêtre de contexte par modèle. Les modifications s’appliquent aux nouveaux événements sans redémarrer le serveur.

Alertes et incidents

Permission	Routes HTTP	Ce qu’elle autorise
`alerts:read`	`GET /alerts`, `GET /alerts/:id`	Consulter les définitions d’alertes configurées.
`alerts:write`	`POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test`	Créer, modifier, supprimer et tester des définitions d’alertes.
`incidents:read`	`GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers`	Consulter les incidents et leur historique de triage.
`incidents:write`	`POST /alerts/:id/incidents`	Ouvrir manuellement un incident sur une alerte existante.
`incidents:ack`	`POST /alerts/incidents/:iid/ack`, `POST /alerts/incidents/:iid/assign`, `POST /alerts/incidents/:iid/resolve`, `POST /alerts/incidents/:iid/comments`, `POST /alerts/incidents/:iid/subscribe`, `POST /alerts/incidents/:iid/unsubscribe`	Accuser réception, assigner, résoudre et commenter des incidents.

Audits

Permission	Routes HTTP	Ce qu’elle autorise
`audits:read`	`GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid`	Consulter les définitions d’audits, l’historique des exécutions et les résultats.
`audits:write`	`POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status`	Créer, modifier, supprimer et exécuter des audits ; effectuer le triage des résultats (accuser réception / mettre en sourdine / rejeter / résoudre / rouvrir / assigner).

Lors du déploiement des Audits, les bénéficiaires existants ont vu leurs droits élargis selon les mêmes formes de rôles que les alertes : tout utilisateur et ensemble de permissions détenant alerts:read a obtenu audits:read, et tout détenteur de alerts:write a obtenu audits:write. Les clés API existantes n’ont pas été élargies — accordez audits:* à une clé explicitement si elle a besoin de la surface d’audit.

Les grants stockés du jeton legacy alerts:ack sont interprétés comme incidents:ack, afin que les personnes d’astreinte conservent leur accès sans devoir régénérer leur clé. Ce jeton n’est plus assignable depuis l’éditeur d’utilisateurs du tableau de bord ; la matrice propose incidents:ack à la place.

L’endpoint de sélection des 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 disposer de users:read.

Un lecteur de tableaux de bord a besoin à la fois de dashboards:read (pour charger les vues sauvegardées) et de 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 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 intentionnellement non authentifiés ; ils constituent le flux de connexion et la sonde de disponibilité. GET /access-granters requiert une clé valide mais aucune permission spécifique, de sorte que tout utilisateur connecté peut voir quels administrateurs contacter concernant les changements d’accès.

Ensembles de permissions

Les ensembles de permissions vous permettent d’appliquer un rôle nommé plutôt que de sélectionner manuellement des jetons individuels à chaque fois. Plutôt que de choisir une douzaine de permissions une par une pour chaque nouvel utilisateur du tableau de bord ou clé API, vous sélectionnez un ensemble, et tous les membres qui y sont assignés bénéficient d’un grant cohérent et vérifiable. La modification d’un ensemble personnalisé réapplique le nouveau grant à chaque utilisateur qui y est déjà assigné, de sorte qu’un changement de rôle est une seule modification plutôt qu’un balayage de tous les membres. Chaque organisation est initialisée avec trois ensembles intégrés :

Ensemble	Permissions	Destiné à
`read-only`	`events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read`	Accès en lecture seule sur toutes les surfaces opérationnelles.
`standard`	tout ce qui est dans `read-only`, plus `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use`	Lecture seule plus les actions quotidiennes des personnes d’astreinte : exécuter des requêtes, réévaluer des sessions, accuser réception d’incidents et utiliser l’assistant IA.
`admin`	toutes les permissions assignables	Contrôle total de l’organisation.

Les trois ensembles intégrés sont immuables ; leurs noms ont toujours la même signification, de sorte que 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 accessibles dans le tableau de bord et gérés via l’API sur GET /permission-sets (liste, contrôlée par users:read) et POST /permission-sets / PUT /permission-sets/:name / DELETE /permission-sets/:name (créer, modifier, supprimer un ensemble personnalisé, contrôlé par settings:write). La suppression ou la modification d’un ensemble intégré est refusée. L’appartenance à un ensemble est ce qui alimente deux autres fonctionnalités :

DEFAULT_USER_PERMISSIONS (le grant présélectionné lorsqu’un administrateur ouvre + nouvel utilisateur) est par défaut l’ensemble standard. Voir Déploiement.
L’option --set sur agenteye-orgctl (gestion des membres par l’opérateur) initialise un membre à partir d’un ensemble nommé, que vous affinez ensuite avec --add / --remove. Voir Gestion des locataires.

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 jetons non assignables ; le serveur refuserait sinon la clé avec HTTP 422. Les utilisateurs du tableau de bord ne sont pas soumis à cette restriction.

Clé admin de bootstrap

La clé admin est l’unique credential racine qui permet à un opérateur de mettre en place l’accès à partir de rien : avec elle, vous pouvez créer toutes les autres clés à portée limitée, 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 afin 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 effectue un upsert de cette valeur comme clé admin avec toutes les permissions. Pour effectuer une rotation : modifiez ADMIN_KEY avec un nouveau secret et redémarrez le serveur.

Portée des organisations

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) est géré avec le CLI agenteye-orgctl qui s’exécute dans le pod serveur ; il n’existe pas d’API HTTP ni de bouton dans le tableau de bord pour cela. Voir Gestion des locataires. 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 estampillée sur la clé à sa création et appliquée à chaque requête. Les deux clés de bootstrap font 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 conteneur du tableau de bord s’authentifie avec la clé admin afin de pouvoir transmettre les requêtes par organisation au nom des membres connectés. Les déploiements mono-locataire n’ont pas à s’en préoccuper ; toutes les clés appartiennent à l’organisation default intégrée.

Création de clés

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

Clé de collecteur (ingestion uniquement)

curl -s -X POST http://your-server:8080/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-collector",
    "key": "your-collector-secret",
    "permissions": ["events:add"]
  }'

Clé de tableau de bord (lecture seule)

curl -s -X POST http://your-server:8080/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dashboard",
    "key": "your-dashboard-secret",
    "permissions": ["events:read", "keys:read"]
  }'

Lorsque vous créez une clé via l’API HTTP, vous fournissez vous-même la valeur key ; choisissez un secret fort et conservez-le en sécurité. (Le tableau de bord fonctionne à l’inverse : il génère un secret fort pour vous et l’affiche 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 :

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "prod-collector",
  "permissions": ["events:add"],
  "created_at": "2026-04-01T12:00:00Z"
}

Listage des clés

curl -s http://your-server:8080/keys \
  -H "Authorization: Bearer $ADMIN_KEY"

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

Désactivation d’une clé

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

curl -s -X POST http://your-server:8080/keys/<id>/disable \
  -H "Authorization: Bearer $ADMIN_KEY"

Régénération d’une clé

Génère un nouveau secret pour une clé existante. L’ancien secret est invalidé immédiatement.

curl -s -X POST http://your-server:8080/keys/<id>/regenerate \
  -H "Authorization: Bearer $ADMIN_KEY"

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 consulter la liste, et de 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 capacité de créer des clés sans la capacité de modifier la portée des clés existantes, ou vice versa. La clé admin couvre toutes ces opérations. 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 conservez-le en sécurité ; il ne sera plus jamais affiché, exactement comme lors d’une régénération. Vous pouvez néanmoins choisir directement les permissions de la clé, ou les initialiser à partir d’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 des actions de régénération et de désactivation ; les clés protégées comme admin sont marquées

Organisation recommandée des clés

Clé	Permissions	Utilisée par
`admin` (bootstrap via la variable d’environnement `ADMIN_KEY`)	toutes	Ops/configuration, et le conteneur du tableau de bord (s’authentifie avec `ADMIN_KEY`, transmet les requêtes utilisateurs avec vérification des permissions)
Clé de collecteur par hôte	`events:add`	Collecteur sur chaque machine agent
`dashboard-assistant` (bootstrap via la variable d’environnement `AGENT_API_KEY`)	`events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run`	Conteneur de l’assistant IA, initialisé automatiquement, protégé ; ne peut pas être modifié via l’API
Clé de télémétrie de l’assistant (optionnelle)	`events:add`	Auto-instrumentation de l’assistant IA, si activée

Clé de l’assistant. 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 fixé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 l’écriture sur les tableaux de bord et la lecture / écriture / exécution des requêtes pour le flux de création « Demander à l’IA d’écrire une requête ». Tout le SQL passe toujours par le même rôle en lecture seule et les mêmes vérifications sql_guard qu’une requête écrite par un utilisateur, de sorte que cela élargit la surface de création, pas la surface de données ; les opérations destructives (queries:delete, dashboards:delete) sont 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 en changeant AGENT_API_KEY et en redémarrant. Les utilisateurs du tableau de bord ont également 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.

​Permissions

​Ingestion et interrogation des événements

​Sessions et évaluations

​Tableaux de bord

​Requêtes sauvegardées (compositeur SQL)

​Assistant IA

​Clés API

​Utilisateurs du tableau de bord

​Paramètres opérationnels

​Alertes et incidents

​Audits

​Ensembles de permissions

​Clé admin de bootstrap

​Portée des organisations

​Création de clés

​Clé de collecteur (ingestion uniquement)

​Clé de tableau de bord (lecture seule)

​Listage des clés

​Désactivation d’une clé

​Régénération d’une clé

​Gestion des clés dans le tableau de bord

​Organisation recommandée des clés