> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Clés API
> Documentation des clés API AgentEye.
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). |
### Clés API
| 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 :
### 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](/fr/agenteye/deployment).
* **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](/fr/agenteye/tenant-management).
> 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](/fr/agenteye/tenant-management). 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)
```bash theme={null}
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)
```bash theme={null}
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](#key-management-in-the-dashboard).) La réponse confirme que la clé a été créée :
```json theme={null}
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "prod-collector",
"permissions": ["events:add"],
"created_at": "2026-04-01T12:00:00Z"
}
```
***
## Listage des clés
```bash theme={null}
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é.
```bash theme={null}
curl -s -X POST http://your-server:8080/keys//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.
```bash theme={null}
curl -s -X POST http://your-server:8080/keys//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).
***
## 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`.