failproofai 1.0.1-beta.0 → 1.0.1

package/.next/standalone/docs-old/de/agenteye/api-keys.mdx

@@ -0,0 +1,280 @@
+---
+title: "API Keys"
+description: "API keys steuern, wer und was Ihren Failproof AI Observability-Server erreichen kann – ein Collector kann damit Events senden, ohne jemals Lese- oder Adminrechte zu erhalten."
+---
+
+
+API keys steuern, wer und was Ihren Failproof AI Observability-Server erreichen kann – ein Collector kann damit Events senden, ohne jemals Lese- oder Adminrechte zu erhalten. Jeder Key trägt eine oder mehrere Berechtigungen, und jede Berechtigung sichert bestimmte Server-Routen ab; Sie vergeben nur die Berechtigungen, die ein Job tatsächlich benötigt. Die meisten Deployments erstellen lediglich drei Arten von Keys.
+
+## Die 3 Keys, die die meisten Deployments benötigen
+
+| Key | Berechtigungen | Wird verwendet von |
+|---|---|---|
+| Collector-Key | `events:add` | Dem `agenteye-collector` auf jeder Agent-Maschine, um Events zu senden. |
+| Dashboard-Leseschlüssel | `events:read`, `keys:read` | Einem Read-only-Operator oder einer Integration, die Daten abfragt, ohne sie zu verändern. |
+| Bootstrap-Admin-Key | alle Berechtigungen | Dem Operator, der die Instanz erstmals einrichtet (zusammen mit dem Dashboard). Wird aus der Umgebungsvariable `ADMIN_KEY` befüllt. Siehe [Bootstrap-Admin-Key](#bootstrap-admin-key). |
+
+Beginnen Sie hier. Den vollständigen Berechtigungskatalog weiter unten benötigen Sie nur, wenn Sie einen enger gefassten, benutzerdefiniert abgegrenzten Key brauchen. Siehe auch [Empfohlenes Key-Layout](#recommended-key-layout) und [Keys erstellen](#creating-keys).
+
+---
+
+## Berechtigungen
+
+Der Server erzwingt einen festen Berechtigungskatalog; jede Berechtigung sichert bestimmte HTTP-Routen ab. Ein **Admin-Key** besitzt alle davon; ein scoped Key besitzt die Teilmenge, die Sie bei der Erstellung vergeben. Unbekannte Berechtigungs-Strings werden beim Erstellen eines Keys abgelehnt.
+
+> **Hinweis:** Zwei gültige Berechtigungen sind ausschließlich für Menschen/das Dashboard bestimmt und können keinem API-Key zugewiesen werden: `orgs:admin` (Instanz-Administration, die dem Operator vorbehalten ist) und `keys:update`. Eine Anfrage an `POST /keys` oder `PATCH /keys/:id`, die versucht, eine dieser Berechtigungen zu vergeben, wird mit HTTP 422 abgelehnt. Warum ein Bearer-Key zwar Keys erstellen, aber nie bearbeiten darf, erläutert die Zeile zu `keys:update` weiter unten.
+
+### Events: Ingest & Abfrage
+
+| Berechtigung | HTTP-Routen | Was sie erlaubt |
+|---|---|---|
+| `events:add` | `POST /events` | Batches von Events eines Collectors einlesen. Die einzige Berechtigung, die ein Collector benötigt. |
+| `events:read` | `GET /events`, `GET /events/latency_aggregate`, `GET /events/environments`, `GET /events/models`, `GET /sessions/:session_id/export` | Events abfragen, bekannte Umgebungen auflisten, im Datensatz gesehene Modellbezeichner auflisten (verwendet von der Models-Ansicht und Modellfiltern), das Latenz-Aggregat für die Heatmap/Perzentilband berechnen und eine Session als JSONL exportieren. Die gemeinsamen Filter-Leisten-Facet-Endpunkte `GET /events/environments` und `GET /events/agent_ids` sind sowohl mit `events:read` **als auch** mit `evaluations:read` erreichbar, sodass die Sessions-Seite (gesichert durch `evaluations:read`) dieselbe organisationsweite Facette nutzen kann. `GET /events/models` gehört nicht dazu: es erfordert `events:read`; ein Principal, der nur `evaluations:read` besitzt, erhält einen 403. |
+
+### Sessions & Evaluierungen
+
+| Berechtigung | HTTP-Routen | Was sie erlaubt |
+|---|---|---|
+| `evaluations:read` | `GET /sessions`, `GET /evaluations`, `GET /evaluations/aggregate`, `GET /evaluations/environments`, `GET /evaluation-jobs` | Sessions auflisten, Evaluierungsergebnisse lesen, die zusammengefasste Eval-Gesundheit für Dashboards sowie den Status der Evaluierungsjob-Worker-Queue einsehen. |
+| `evaluations:trigger` | `POST /sessions/:session_id/re-evaluate` | Eine erneute Evaluierung für eine abgeschlossene Session manuell in die Warteschlange stellen. |
+
+### Dashboards
+
+| Berechtigung | HTTP-Routen | Was sie erlaubt |
+|---|---|---|
+| `dashboards:read` | `GET /dashboards`, `GET /dashboards/:id`, `GET /dashboards/:id/tiles` | Dashboards auflisten, eines laden und seine Tiles lesen. |
+| `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` | Dashboards erstellen und bearbeiten, Tiles hinzufügen/bearbeiten/entfernen und das Tile-Raster neu anordnen. |
+| `dashboards:delete` | `DELETE /dashboards/:id` | Ein gesamtes Dashboard löschen (das Löschen auf Tile-Ebene liegt unter `dashboards:write`). |
+
+### Gespeicherte Abfragen (SQL-Composer)
+
+| Berechtigung | HTTP-Routen | Was sie erlaubt |
+|---|---|---|
+| `queries:read` | `GET /queries`, `GET /queries/:id`, `GET /queries/schema` | Gespeicherte Abfragen auflisten, eine laden und das Read-only-Schema des Composers einsehen. |
+| `queries:write` | `POST /queries`, `PUT /queries/:id` | Gespeicherte Abfragen erstellen und bearbeiten. SQL wird weiterhin über dieselbe Read-only-Rolle und dieselben SQL-Prüfungen wie ein `queries:run`-Aufruf geleitet. |
+| `queries:delete` | `DELETE /queries/:id` | Eine gespeicherte Abfrage löschen. |
+| `queries:run` | `POST /queries/run` | Gespeichertes oder Ad-hoc-SQL gegen die Read-only-Rolle des Composers ausführen. |
+
+### KI-Assistent
+
+| Berechtigung | HTTP-Routen | Was sie erlaubt |
+|---|---|---|
+| `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` | Mit dem KI-Assistenten sprechen und eigene (private) Konversationen verwalten. Auf **Benutzerebene** erforderlich, um das Assistenten-Dock zu sehen; der eigene Key des Assistenten ist `dashboard-assistant` und wird separat befüllt (siehe unten). |
+
+### API-Keys
+
+| Berechtigung | HTTP-Routen | Was sie erlaubt |
+|---|---|---|
+| `keys:create` | `POST /keys` | Einen neuen scoped API-Key erstellen. Gewährt **nicht** das Bearbeiten der Berechtigungen eines vorhandenen Keys (das ist `keys:update`). |
+| `keys:read` | `GET /keys` | Vorhandene Keys auflisten. Secrets werden von diesem Endpunkt nie zurückgegeben. |
+| `keys:update` | `PATCH /keys/:id` | Die Berechtigungen eines vorhandenen Keys bearbeiten. Eine **ausschließlich für Menschen/das Dashboard** bestimmte Berechtigung; sie kann keinem API-Key zugewiesen werden (ein Bearer-Key darf Keys erstellen, aber nie bearbeiten). |
+| `keys:disable` | `POST /keys/:id/disable` | Einen Key widerrufen. Geschützte Keys (`admin`, `dashboard-assistant`) können nicht deaktiviert werden; rotieren Sie diese per Umgebungsvariable + Neustart. |
+| `keys:regenerate` | `POST /keys/:id/regenerate` | Das Secret eines Keys rotieren. Geschützte Keys können über diese Route nicht neu generiert werden. |
+
+### Dashboard-Benutzer
+
+| Berechtigung | HTTP-Routen | Was sie erlaubt |
+|---|---|---|
+| `users:create` | `POST /users`, `GET /users/defaults` | Einen neuen Dashboard-Benutzer einladen (sendet eine E-Mail mit Einmalpasscode (OTP) zur Anmeldung) und den dashboard-konfigurierten Standard-Berechtigungssatz lesen, der das Einladeformular vorausfüllt. |
+| `users:read` | `GET /users`, `GET /users/:id` | Benutzer auflisten und einen einzelnen Benutzerdatensatz laden. |
+| `users:update` | `PUT /users/:id` | Die Berechtigungen eines Benutzers bearbeiten. Änderungen lösen eine Benachrichtigungs-E-Mail über Berechtigungsänderungen an den betroffenen Benutzer aus und werden bei der nächsten Anfrage wirksam; eine erneute Anmeldung ist nicht erforderlich. |
+| `users:delete` | `DELETE /users/:id`, `POST /users/:id/enable` | Einen Benutzer deaktivieren (widerruft seine Sessions sofort) und einen zuvor deaktivierten Benutzer wieder aktivieren. |
+
+Diese Berechtigungen unterstützen die **Users**-Seite im Dashboard, auf der die vergebenen Scopes jedes Mitglieds als Chips angezeigt werden:
+
+![Die Users-Seite: eine Karte pro Dashboard-Benutzer mit E-Mail-Adresse, vergebenen Berechtigungen sowie Bearbeiten- und Deaktivieren-Steuerelementen](/agenteye/images/users.png)
+
+### Betriebliche Einstellungen
+
+| Berechtigung | HTTP-Routen | Was sie erlaubt |
+|---|---|---|
+| `settings:read` | `GET /settings`, `GET /settings/schema`, `GET /settings/model-context-windows`, `GET /settings/model-context-windows/resolve` | Dashboard-verwaltete Betriebseinstellungen und ihre Metadaten anzeigen; modellspezifische Context-Window-Overrides auflisten; und das effektive Window für ein Modell auflösen. |
+| `settings:write` | `PUT /settings/:key`, `PUT /settings/model-context-windows`, `DELETE /settings/model-context-windows` | Betriebseinstellungen bearbeiten sowie modellspezifische Context-Window-Overrides hinzufügen, ändern oder entfernen. Änderungen wirken sich auf neue Events aus, ohne den Server neu starten zu müssen. |
+
+![Die Settings-Seite: dashboard-verwaltete Betriebseinstellungen wie erlaubte Anmeldemethoden und Session-/OTP-Lebensdauern, bearbeitbar ohne Neustart](/agenteye/images/settings.png)
+
+### Alarme & Vorfälle
+
+| Berechtigung | HTTP-Routen | Was sie erlaubt |
+|---|---|---|
+| `alerts:read` | `GET /alerts`, `GET /alerts/:id` | Konfigurierte Alarm-Definitionen anzeigen. |
+| `alerts:write` | `POST /alerts`, `PUT /alerts/:id`, `DELETE /alerts/:id`, `POST /alerts/:id/test` | Alarm-Definitionen erstellen, bearbeiten, löschen und testweise auslösen. |
+| `incidents:read` | `GET /alerts/incidents`, `GET /alerts/incidents/:iid`, `GET /alerts/incidents/:iid/comments`, `GET /alerts/incidents/:iid/subscribers` | Vorfälle und ihren Triage-Verlauf anzeigen. |
+| `incidents:write` | `POST /alerts/:id/incidents` | Einen Vorfall manuell zu einem bestehenden Alarm öffnen. |
+| `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` | Vorfälle bestätigen, zuweisen, auflösen und kommentieren. |
+
+### Audits
+
+| Berechtigung | HTTP-Routen | Was sie erlaubt |
+|---|---|---|
+| `audits:read` | `GET /audits`, `GET /audits/:id`, `GET /audits/:id/runs`, `GET /audits/findings`, `GET /audits/findings/:fid` | Audit-Definitionen, Ausführungsverlauf und Befunde anzeigen. |
+| `audits:write` | `POST /audits`, `PUT /audits/:id`, `DELETE /audits/:id`, `POST /audits/:id/run`, `POST /audits/findings/:fid/status` | Audits erstellen, bearbeiten, löschen und ausführen; Befunde triagieren (bestätigen / stummschalten / verwerfen / lösen / erneut öffnen / zuweisen). |
+
+> **Hinweis:** Um einem Key die Audit-Oberfläche zu geben, vergeben Sie `audits:*` explizit. Wie bestehende Berechtigungsinhaber migriert wurden, als Audits eingeführt wurden, erfahren Sie unter [Upgrade- und Abwärtskompatibilitätshinweise](#upgrade-and-backward-compatibility-notes).
+
+> Der Empfänger-Auswahl-Endpunkt `GET /alerts/recipients` (der die Mitglieds-E-Mail-Adressen auflistet, die ein Alarm-Editor benachrichtigen kann) ist für Inhaber von **entweder** `alerts:read` **oder** `alerts:write` erreichbar, sodass Alarm-Editoren die Auswahl befüllen können, ohne `users:read` zu benötigen.
+
+> Ein Dashboard-Betrachter benötigt **sowohl** `dashboards:read` (zum Laden der gespeicherten Ansichten) als auch `evaluations:read` (die Gesundheitsmetriken werden aus Evaluierungsdaten berechnet). Vergeben Sie `dashboards:write`, um einem Benutzer das Erstellen oder Bearbeiten von Dashboards zu erlauben, und `dashboards:delete` zum Löschen.
+
+> `/health` und `/auth/*` (OTP-Anfrage, OTP-Verifizierung, Session-Prüfung, Logout) sind designbedingt nicht authentifiziert; sie sind der Anmeldeablauf und der Liveness-Probe. `GET /access-granters` erfordert einen gültigen Key, aber keine spezifische Berechtigung, sodass jeder angemeldete Benutzer sehen kann, welche Admins er bei Zugriffsänderungen kontaktieren soll.
+
+---
+
+## Berechtigungs-Sets
+
+Berechtigungs-Sets ermöglichen es Ihnen, eine benannte Rolle anzuwenden, anstatt jedes Mal einzelne Tokens manuell auszuwählen. Anstatt für jeden neuen Dashboard-Benutzer oder API-Key ein Dutzend Berechtigungen einzeln auszuwählen, wählen Sie ein Set, und alle ihm zugeordneten Personen tragen eine konsistente, nachvollziehbare Zuweisung. Das Bearbeiten eines benutzerdefinierten Sets wendet die neue Zuweisung auf jeden bereits zugeordneten Benutzer erneut an, sodass eine Rollenänderung eine einzige Bearbeitung und kein Durchgehen aller Mitglieder ist.
+
+Jede Organisation wird mit drei integrierten Sets befüllt:
+
+| Set | Berechtigungen | Gedacht für |
+|---|---|---|
+| `read-only` | `events:read`, `keys:read`, `users:read`, `evaluations:read`, `dashboards:read`, `queries:read`, `settings:read`, `alerts:read`, `audits:read`, `incidents:read` | Nur-Lese-Zugriff auf alle Betriebsoberflächen. |
+| `standard` | alles in `read-only`, plus `evaluations:trigger`, `queries:run`, `incidents:ack`, `agent:use` | Read-only plus die alltäglichen On-Call-Aktionen: Abfragen ausführen, Sessions neu evaluieren, Vorfälle bestätigen und den KI-Assistenten nutzen. |
+| `admin` | jede zuweisbare Berechtigung | Vollständige Kontrolle über die Organisation. |
+
+Die drei integrierten Sets sind **unveränderlich**; ihre Namen bedeuten immer dasselbe, sodass `read-only`, `standard` und `admin` sicher in Richtlinien und beim Onboarding referenziert werden können. Ein Operator kann zusätzliche **benutzerdefinierte Sets** erstellen, um organisationsspezifische Rollen abzubilden (z. B. eine Rolle „Dashboard-Autor" oder eine Rolle „Nur-Collector").
+
+Sets sind im Dashboard sichtbar und werden über die API verwaltet: `GET /permission-sets` (auflisten, gesichert durch `users:read`) sowie `POST /permission-sets` / `PUT /permission-sets/:name` / `DELETE /permission-sets/:name` (benutzerdefiniertes Set erstellen, bearbeiten, löschen, gesichert durch `settings:write`). Das Löschen oder Bearbeiten eines integrierten Sets wird abgelehnt.
+
+Set-Mitgliedschaft unterstützt zwei weitere Funktionen:
+
+- **`DEFAULT_USER_PERMISSIONS`** (die Zuweisung, die vorausgewählt ist, wenn ein Admin **+ neuer Benutzer** öffnet) ist standardmäßig auf das `standard`-Set gesetzt.
+- **Das `--set`-Flag** bei `agenteye-orgctl` (Operator-Mitgliederverwaltung) startet ein Mitglied mit einem benannten Set, das Sie dann mit `--add` / `--remove` verfeinern.
+
+> **Hinweis:** Wenn ein Set eine Berechtigung enthält, die nicht Key-zuweisbar ist (z. B. ein benutzerdefiniertes Set mit `keys:update`), werden beim Befüllen eines Keys aus diesem Set die nicht zuweisbaren Tokens weggelassen; der Server würde den Key andernfalls mit HTTP 422 ablehnen. Für Dashboard-Benutzer gilt diese Einschränkung nicht.
+
+---
+
+## Bootstrap-Admin-Key
+
+Der Admin-Key ist die einzige Root-Berechtigung, mit der ein Operator den Zugang von Grund auf einrichten kann: Damit können Sie jeden anderen scoped Key erstellen, die ersten Dashboard-Benutzer einladen und die Instanz konfigurieren, bevor ein anderer Key existiert. Es ist der einzige Key, den Sie nicht über die Keys-API erstellen; er wird aus der Umgebung bereitgestellt, damit der Server beim ersten Start erreichbar ist.
+
+Setzen Sie die Umgebungsvariable `ADMIN_KEY` auf dem Server. Bei jedem Start führt der Server ein Upsert dieses Werts als Admin-Key mit allen Berechtigungen durch.
+
+Zum Rotieren: Ändern Sie `ADMIN_KEY` auf ein neues Secret und starten Sie den Server neu.
+
+---
+
+## Organisations-Scoping
+
+**Organisationen selbst werden vom Operator außerhalb des Bandes erstellt und verwaltet, nicht über diese Keys-API.** Der Lebenszyklus von Organisationen und Mitgliedern (erstellen/umbenennen/löschen/bereinigen einer Org; Mitglied hinzufügen/aktualisieren/entfernen) erfolgt mit der **`agenteye-orgctl`**-CLI; dafür gibt es keine HTTP-API oder Dashboard-Schaltfläche. Was *unverändert* bleibt: **Pro-Org-API-Keys werden weiterhin im Dashboard (oder über diese Keys-API)** von Org-Mitgliedern erstellt.
+
+In einem Multi-Org-Deployment gehört jeder Key, den ein Org-Mitglied erstellt (über diese Keys-API oder die Dashboard-**Keys**-Seite), zu **einer Organisation** und kann ausschließlich die Daten dieser Org lesen oder schreiben; die Org wird beim Erstellen auf den Key gestempelt und bei jeder Anfrage durchgesetzt. Die beiden Bootstrap-Keys sind die einzige Ausnahme: Der `admin`-Key (befüllt aus `ADMIN_KEY`) und der `dashboard-assistant`-Key (befüllt aus `AGENT_API_KEY`) sind **instanzweit gültig** (sie tragen keine Org). Das Dashboard authentifiziert sich mit dem `admin`-Key, damit es Pro-Org-Anfragen im Namen angemeldeter Mitglieder weiterleiten kann. Single-Tenant-Deployments müssen sich darum nicht kümmern; alle Keys gehören zur integrierten `default`-Org.
+
+---
+
+## Keys erstellen
+
+Verwenden Sie den Admin-Key (oder einen beliebigen Key mit der Berechtigung `keys:create`), um weitere scoped Keys zu erstellen.
+
+### Collector-Key (nur Ingest)
+
+```bash
+curl -s -X POST http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "prod-collector",
+    "key": "your-collector-secret",
+    "permissions": ["events:add"]
+  }'
+```
+
+### Dashboard-Key (nur Lesen)
+
+```bash
+curl -s -X POST http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "dashboard",
+    "key": "your-dashboard-secret",
+    "permissions": ["events:read", "keys:read"]
+  }'
+```
+
+Wenn Sie einen Key über die HTTP-API erstellen, geben Sie den `key`-Wert selbst an; wählen Sie ein starkes Secret und speichern Sie es sicher. (Im Dashboard funktioniert es umgekehrt: Es generiert ein starkes Secret für Sie und zeigt es einmalig bei der Erstellung an; siehe [Key-Verwaltung im Dashboard](#key-management-in-the-dashboard).) Die Antwort bestätigt, dass der Key erstellt wurde:
+
+```json
+{
+  "id": "550e8400-e29b-41d4-a716-446655440000",
+  "name": "prod-collector",
+  "permissions": ["events:add"],
+  "created_at": "2026-04-01T12:00:00Z"
+}
+```
+
+---
+
+## Keys auflisten
+
+```bash
+curl -s http://your-server/keys \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+Key-Secrets werden in Listenantworten nicht zurückgegeben – nur IDs, Namen und Berechtigungen.
+
+---
+
+## Einen Key deaktivieren
+
+Das Deaktivieren widerruft den Zugriff sofort, ohne den Key-Datensatz zu löschen.
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/disable \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+---
+
+## Einen Key neu generieren
+
+Generiert ein neues Secret für einen vorhandenen Key. Das alte Secret wird sofort ungültig.
+
+```bash
+curl -s -X POST http://your-server/keys/<id>/regenerate \
+  -H "Authorization: Bearer $ADMIN_KEY"
+```
+
+Die Antwort enthält das neue Klartext-Secret, das **nur einmal angezeigt** wird.
+
+---
+
+## Key-Verwaltung im Dashboard
+
+Die **Keys**-Seite im Dashboard bietet eine Benutzeroberfläche für alle oben genannten Operationen. Sie benötigen einen Key mit der Berechtigung `keys:read`, um die Liste anzuzeigen, sowie `keys:create` / `keys:update` / `keys:disable` / `keys:regenerate` für die Aktionen Erstellen / Bearbeiten / Deaktivieren / Neu generieren. Das Bearbeiten der Berechtigungen eines Keys (`keys:update`) ist vom Erstellen eines Keys (`keys:create`) getrennt, sodass Sie einem Operator die Möglichkeit geben können, Keys zu erstellen, ohne bestehende neu zu scopieren – oder umgekehrt. Der Admin-Key deckt all diese Bereiche ab.
+
+Wenn Sie einen Key im Dashboard erstellen, geben Sie das Secret nicht selbst an; das Dashboard generiert ein starkes Secret für Sie und zeigt es **einmalig** bei der Erstellung an. Kopieren Sie es sofort und speichern Sie es sicher; es wird nie wieder angezeigt – genau wie beim Neu-Generieren. Sie können die Berechtigungen des Keys trotzdem direkt auswählen oder sie aus einem Berechtigungs-Set übernehmen (siehe unten).
+
+![Die API-Keys-Seite: eine Karte pro Key mit Name, vergebenen Berechtigungen und Erstellungszeitpunkt sowie Aktionen zum Neu-Generieren und Deaktivieren; geschützte Keys wie `admin` sind gekennzeichnet](/agenteye/images/api-keys.png)
+
+---
+
+## Empfohlenes Key-Layout
+
+| Key | Berechtigungen | Wird verwendet von |
+|---|---|---|
+| `admin` (Bootstrap via `ADMIN_KEY`-Umgebungsvariable) | alle | Ops/Einrichtung sowie dem Dashboard (authentifiziert sich mit `ADMIN_KEY`, leitet Benutzeranfragen mit Berechtigungsprüfungen weiter) |
+| Pro-Host-Collector-Key | `events:add` | Collector auf jeder Agent-Maschine |
+| `dashboard-assistant` (Bootstrap via `AGENT_API_KEY`-Umgebungsvariable) | `events:read`, `evaluations:read`, `dashboards:read`, `dashboards:write`, `queries:read`, `queries:write`, `queries:run` | KI-Assistent, automatisch befüllt, **geschützt**; kann nicht über die API bearbeitet werden |
+| Assistent-Telemetrie-Key (optional) | `events:add` | KI-Assistent-Selbst-Instrumentierung, falls aktiviert |
+
+> **Hinweis:** Der Key des Assistenten wird **automatisch** vom Server aus der Umgebungsvariable `AGENT_API_KEY` befüllt (dasselbe Secret, das der Agent als `AGENTEYE_API_KEY` präsentiert); es gibt keinen manuellen Key-Erstellungsschritt und keinen Admin-Key dabei. Seine Berechtigungen sind im Quellcode festgelegt, sodass der Scope nicht durch Fehlkonfiguration erweitert werden kann: Lesezugriff auf Events/Evaluierungen/Dashboards, plus Dashboards-write und Queries-read/write/run für den Authoring-Flow „KI nach einer Abfrage fragen". Sämtliches SQL durchläuft weiterhin dieselbe Read-only-Rolle und denselben gesicherten SQL-Pfad wie eine benutzerverfasste Abfrage, sodass dies die *Authoring-Oberfläche*, nicht die Datenoberfläche erweitert; destruktive Operationen (`queries:delete`, `dashboards:delete`) bleiben bewusst vom Assistenten-Key ausgeschlossen. Wie der `admin`-Key ist er **geschützt**: Er kann nicht über die Keys-API deaktiviert oder neu generiert werden, sondern nur durch Ändern von `AGENT_API_KEY` und Neustart rotiert werden. Dashboard-*Benutzer* benötigen zusätzlich die Berechtigung `agent:use`, um den Assistenten zu sehen und zu nutzen. Wenn Sie die Selbst-Instrumentierung aktivieren, geben Sie dem Assistenten einen separaten Key, der nur `events:add` enthält.
+
+---
+
+## Upgrade- und Abwärtskompatibilitätshinweise
+
+Diese Hinweise sind nur relevant, wenn Sie eine bestehende Instanz aktualisieren; neue Deployments können sie überspringen.
+
+> Als Audits eingeführt wurden, wurden bestehende Berechtigungsinhaber entsprechend denselben Rollenformen wie bei Alarmen erweitert: Jeder Benutzer und jedes Berechtigungs-Set, das `alerts:read` enthielt, erhielt `audits:read`; jeder Inhaber von `alerts:write` erhielt `audits:write`. Bestehende API-Keys wurden **nicht** erweitert. Vergeben Sie `audits:*` explizit an einen Key, wenn er die Audit-Oberfläche benötigt.
+
+> Gespeicherte Zuweisungen des veralteten Tokens `alerts:ack` werden als `incidents:ack` geparst, sodass On-Caller den Zugriff ohne erneute Key-Ausgabe behalten. Das Token ist im Benutzer-Editor des Dashboards nicht mehr zuweisbar; die Matrix bietet stattdessen `incidents:ack` an.
+
+---
+
+## Nächste Schritte
+
+- [Python SDK](/de/agenteye/python-sdk): Wie Ihr Agent-Code sich beim Senden von Events authentifiziert.
+- [Security](/de/agenteye/security): Wie Anmeldung, Zugriffskontrolle und organisationsweite Datenisolierung funktionieren.

package/.next/standalone/docs-old/de/agenteye/assistant.mdx

@@ -0,0 +1,63 @@
+---
+title: "KI-Assistent"
+description: "Stell deinen Agentendaten eine Frage auf Deutsch und erhalte eine Antwort, die direkt auf die Belege verlinkt."
+---
+
+
+Stell deinen Agentendaten eine Frage in gewöhnlicher Sprache und erhalte eine Antwort, die direkt auf die Belege verlinkt. Kein SQL schreiben, kein Durchsuchen von Dashboards – der **Failproof AI Observability**-Assistent ist der schnellste Weg für jeden in deinem Team, Antworten zu euren Agenten zu bekommen.
+
+![Der Failproof AI Observability-Assistent beantwortet eine Frage in natürlicher Sprache im Dashboard und zeigt dabei eine Live-Agenten-Aktivitätstabelle, eine Aufschlüsselung der Modellnutzung pro Agent und schriftliche Zusammenfassungen – die ausgeführten Abfragen werden inline angezeigt](/agenteye/images/assistant.png)
+*Frag in natürlicher Sprache und erhalte eine Antwort, die aus deinen eigenen Daten aufgebaut ist. Hier wird aufgeschlüsselt, welche Agenten am stärksten ausgelastet sind und welche Modelle sie verwenden – die ausgeführten Abfragen werden angezeigt, damit du jede Zahl nachvollziehen kannst.*
+
+Es gibt nichts zu lernen. Öffne den Chat, tippe, was du wissen möchtest, und folge den Links, die zurückgegeben werden:
+
+```
+You:  which sessions errored today?
+AI:   5 sessions errored today, newest first. Each one is linked:
+      • checkout-agent   14:02   tool timeout
+      • billing-agent    11:47   unhandled error
+      • ...and 3 more
+
+You:  summarize this session          (asked while viewing a run)
+AI:   This run took 12 steps across 3 tools and failed near the end when a
+      payment tool returned an error. It scored low on your "resolved" eval.
+      Links: the session, the failing event, and that evaluation.
+```
+
+## Einfach fragen und direkt zum Beweis springen
+
+Du hörst auf zu raten und hörst auf, Abfragen zu schreiben. Frag „Wie entwickelt sich die Qualität in Produktion diese Woche?", „Welche Sessions sind heute fehlgeschlagen?" oder „Fasse diese Session zusammen" – und du erhältst in Sekunden eine direkte Antwort, anstatt selbst eine Abfrage zu erstellen und auszuwerten.
+
+Jede Antwort kommt mit ihren Belegen. Der Assistent verlinkt die genauen Sessions, gespeicherten Abfragen und Dashboards, die er zur Antwort verwendet hat – so kannst du durchklicken und bestätigen, anstatt ihm blind zu vertrauen. Außerdem ist er **seitenabhängig**: Frag nach „dieser Session", während du eine betrachtest, und er weiß bereits, welchen Lauf du meinst. Öffne frühere Gespräche später über den Verlaufs-Umschalter erneut und mach dort weiter, wo du aufgehört hast.
+
+## Eine gute Antwort in eine gespeicherte Abfrage oder ein Dashboard verwandeln
+
+Wenn eine Antwort es wert ist, behalten zu werden, bitte den Assistenten, sie zu speichern. Er entwirft das SQL für eine gespeicherte Abfrage oder stellt ein Dashboard aus diesen Abfragen zusammen und zeigt dir dann eine **Genehmigen / Ablehnen**-Karte. Nichts wird gespeichert, bis du auf „Genehmigen" klickst – du bekommst also die Schnelligkeit von „einfach fragen", hast aber immer das letzte Wort.
+
+Auf der **Queries**-Seite geht er noch einen Schritt weiter und wird zum SQL-Autor: Beschreibe die gewünschte Abfrage („zeige Fehlerrate nach Agent für die letzten 7 Tage") und er streamt SQL direkt in den Editor – mit einer Diff-Ansicht, damit du die Änderung **akzeptieren** oder **ablehnen** kannst, bevor sie übernommen wird.
+
+![Die Observability-Queries-Seite und ihr SQL-Editor](/agenteye/images/query-lab.png)
+*Die Queries-Seite: In diesem Editor streamt der Assistent einen schreibgeschützten Entwurf, den du akzeptieren oder ablehnen kannst.*
+
+Das Erstellen von SQL per Frage hier verwendet die Berechtigung `queries:run` – dieselbe, die hinter dem **Ausführen**-Button des Editors steckt. Der Chat überall sonst benötigt `agent:use`.
+
+## Sicher für das gesamte Team
+
+Du kannst den Assistenten für alle öffnen, ohne dir Gedanken darüber machen zu müssen, was er anfassen könnte:
+
+- **Er liest nur, was du bereits sehen kannst.** Antworten sind auf deine eigenen Leseberechtigungen beschränkt, er erweitert also niemals deine Datenfläche.
+- **Jeder Schreibvorgang wartet auf dich.** Gespeicherte Abfragen und Dashboards werden nur nach deinem ausdrücklichen Klick auf „Genehmigen" erstellt – und es gibt keine Einstellung, die diese Schranke deaktiviert.
+- **Er kann niemals etwas löschen.** Es ist kein Lösch-Tool verfügbar, und der Assistent hat keine Löschberechtigung. Löschvorgänge bleiben in deinen Händen, im Dashboard.
+- **Er bleibt in deiner Organisation.** Der Assistent sieht immer nur die Organisation, die du gerade ansiehst.
+- **Deine Fragen gehören dir.** Eingaben und Antworten leben in deiner eigenen Observability-Datenbank; Produktanalysen zeichnen nur Nutzungsmetadaten auf, niemals deinen Fragentext.
+
+## Wo du ihn findest
+
+Der Assistent befindet sich am rechten Rand jeder Seite unter deiner Organisation (`/<org-slug>/...`). Klick auf die Leiste oder drücke `⌘J` / `Ctrl+J`, um sie in das vollständige Chat-Panel zu erweitern, und ziehe an ihrem Rand zum Ändern der Größe – deine Breite wird über Seitenneuladen hinweg gespeichert. Du benötigst die Berechtigung **`agent:use`**, um ihn zu nutzen, andernfalls ist die Leiste ausgegraut. Wenn er für dein Deployment noch nicht aktiviert wurde (er benötigt eine LLM-Verbindung), siehst du eine gedämpfte Leiste anstelle eines funktionierenden Chats.
+
+## Verwandte Themen
+
+- [CLI and agents](/de/agenteye/cli-and-agents)
+- [Queries](/de/agenteye/queries)
+- [Dashboards](/de/agenteye/dashboards)
+- [Evaluation suite](/de/agenteye/evaluation-suite)

package/.next/standalone/docs-old/de/agenteye/audits.mdx

@@ -0,0 +1,54 @@
+---
+title: "Audits: Ihr automatischer Zuverlässigkeitsanalyst"
+description: "Failproof AI Observability sucht nach den Fehlern, für die Sie nie eine Regel geschrieben haben, und liefert Ihnen eine priorisierte, evidenzbasierte Aufgabenliste mit genau dem, was behoben werden muss."
+---
+
+
+Failproof AI Observability sucht nach den Fehlern, für die Sie nie eine Regel geschrieben haben, und liefert Ihnen eine priorisierte, evidenzbasierte Aufgabenliste mit genau dem, was behoben werden muss. Es ist so, als würde ein Analyst jede Nacht Ihre Logs durchforsten und Ihnen morgens die Kurzliste auf den Schreibtisch legen.
+
+<div style={{ position: "relative", width: "100%", paddingBottom: "56.25%", height: 0, overflow: "hidden", borderRadius: "12px", margin: "1.5rem 0" }}>
+  <iframe src="https://www.youtube.com/embed/C5nHKGQIqZQ?autoplay=1&mute=1&loop=1&playlist=C5nHKGQIqZQ&rel=0&playsinline=1" title="Watch: Automatically find where your agent is failing (2 min)" allow="autoplay; encrypted-media; picture-in-picture; fullscreen" allowFullScreen style={{ position: "absolute", top: 0, left: 0, width: "100%", height: "100%", border: 0 }}></iframe>
+</div>
+
+*Ein zweiminütiger Rundgang: vom geplanten Lauf bis zu einer umsetzbaren Lösung.*
+
+![Die Audits-Seite: wiederkehrende Jobs, die Ihre Sessions auf Fehlermuster scannen, jeweils mit Zeitplan und Sensitivität](/agenteye/images/audits.png)
+*Jedes Audit ist ein wiederkehrender Job, der Ihre Sessions auswertet und priorisierte, evidenzbasierte Empfehlungen erstellt.*
+
+## Hören Sie auf zu raten, was als Nächstes behoben werden soll
+
+Alerts erfassen die Probleme, auf die Sie bereits zu achten wissen. Audits erfassen die, die Sie noch nicht kennen. In einem von Ihnen festgelegten Rhythmus liest ein Audit alle Ihre Agent-Sessions durch und sucht nach den Mustern, die es wert sind, behoben zu werden – sodass Sie Ihre Zeit damit verbringen, auf Erkenntnisse zu reagieren, anstatt Logs zu durchblättern und zu hoffen, sie selbst zu entdecken.
+
+Ein einzelner Lauf geht die Fehlermodi an, die Agents in der Produktion tatsächlich zum Scheitern bringen:
+
+- **Fehler-Cluster**: Dieselbe Fehlfunktion, die sich unter einer gemeinsamen Grundursache wiederholt.
+- **Abweichung von einer Baseline**: Verhalten, das sich still und leise von einem bekannt-guten Zeitfenster entfernt.
+- **Zielverfehlung in Transkripten**: Läufe, die technisch abgeschlossen wurden, aber den Auftrag nie erfüllt haben.
+- **Tool-Missbrauch**: Das falsche Tool, fehlerhafte Argumente oder Schleifen, die Aufrufe verschwenden.
+- **Qualitäts- und Kostenabwägungen**: Wo Sie für Output zu viel bezahlen, den Sie günstiger bekommen könnten.
+- **Coverage-Lücken**: Verhalten, das kein Eval und kein Alert überwacht.
+
+Mit einer einzigen **Sensitivitäts**-Einstellung (niedrig, mittel oder hoch) bestimmen Sie, wie gründlich die Suche ist – so kann ein rauschender Staging-Agent und ein abgesicherter Produktions-Agent jeweils auf das gewünschte Signal eingestellt werden.
+
+## Jede Empfehlung kommt mit Belegen
+
+Sie müssen einem Befund niemals blind vertrauen. Jede Empfehlung zitiert die genauen Sessions, aus denen sie stammt, sowie das SQL, das sie aufgedeckt hat – so können Sie die Beweise öffnen und das Problem mit einem Klick bestätigen, anstatt eine Behauptung rückwärts analysieren zu müssen.
+
+Wenn ein Befund ein durchgesickertes Credential betrifft, geht er einen Schritt weiter und verlinkt die einzelnen übereinstimmenden Events. Klicken Sie darauf und Sie landen genau an diesem Moment in der Session, bereits markiert – nicht am Anfang eines langen Transkripts, durch das Sie scrollen müssen. Der Link benennt das Event; er kopiert das erkannte Secret niemals in den Befund, sodass das Lesen eines Befunds kein zweiter Ort ist, an dem Ihr Credential aufgezeichnet ist. Falls ein Event nicht mehr vorhanden ist, weil die Session Ihr Aufbewahrungsfenster überschritten hat, teilt die Seite das klar mit, anstatt Sie im Unklaren zu lassen.
+
+Das ist auch das, was Audits ehrlich hält. Der Server prüft, ob jede zitierte Session tatsächlich existiert, und **verwirft jede Empfehlung, deren Beweise nicht standhalten** – das Audit untersucht also, erfindet aber nie. Was auf Ihrer Liste landet, ist real, reproduzierbar und nach Relevanz gerankt, mit den größten Verbesserungen ganz oben.
+
+## Aus einer Lösung eine Absicherung machen
+
+Ein Problem zu beheben ist nur die halbe Miete. Die andere Hälfte ist sicherzustellen, dass es nicht still und leise zurückkehren kann. Jeder Befund enthält eine **Ein-Klick-Verknüpfung, die einen Wiederholungs-Alert entwirft**, vorausgefüllt mit einem sinnvollen Ausgangstrigger, den Sie anpassen können. Schließen Sie den Befund, aktivieren Sie den Alert – und wenn dieses Muster das nächste Mal auftaucht, werden Sie benachrichtigt, anstatt es bei einem zukünftigen Audit neu zu entdecken.
+
+## Wo Sie es finden
+
+Audits befinden sich im Dashboard unter **`/<org-slug>/audits`** (Seitenleiste zu *analyze* zu *audits*). Das Anzeigen von Läufen und Befunden erfordert **`audits:read`**; das Erstellen, Bearbeiten und Bearbeiten von Audits erfordert **`audits:write`**. Legen Sie Umfang und Rhythmus eines Audits fest und klicken Sie auf **Run now**, wenn Sie sofort Ergebnisse möchten, ohne auf den nächsten geplanten Lauf zu warten.
+
+## Verwandtes
+
+- [Alerts](/de/agenteye/alerts): Werden Sie benachrichtigt, sobald ein Schwellenwert, den Sie bereits kennen, überschritten wird.
+- [Evaluations](/de/agenteye/evaluations): Bewerten Sie jeden Lauf, damit Qualitätsregressionen von selbst auffallen.
+- [Error tracking](/de/agenteye/error-tracking): Gruppieren und verfolgen Sie die Fehler, die Ihre Agents ausgeben.
+- [Incidents](/de/agenteye/incidents): Verfolgen Sie ein von einem Audit aufgedecktes Problem bis zu seiner Lösung.

package/.next/standalone/docs-old/de/agenteye/cli-and-agents.mdx

@@ -0,0 +1,80 @@
+---
+title: "CLI"
+description: "Ihr gesamtes Failproof AI Observability-Deployment, einen Befehl entfernt."
+---
+
+
+Ihr gesamtes Failproof AI Observability-Deployment, einen Befehl entfernt. Prüfen Sie die Produktion, erstellen Sie einen API-Schlüssel oder bestätigen Sie einen Vorfall, ohne Ihr Terminal zu verlassen – und automatisieren Sie alles in CI oder lassen Sie einen Coding-Agenten es auf Englisch erledigen.
+
+```bash
+pipx install agenteye
+agenteye login --email you@example.com      # a 6-digit code lands in your inbox
+agenteye --json sessions --since 24h         # every agent run from the last day, newest first
+```
+
+*Das `agenteye` CLI kommuniziert mit Ihrem Dashboard. Es ist ein anderes Werkzeug als der Collector, der Events an den Server sendet.*
+
+## Ihr gesamtes Deployment, einen Befehl entfernt
+
+Hören Sie auf, zwischen Tabs zu wechseln, um eine schnelle Frage zu beantworten. Das `agenteye` CLI liest Ihre Daten und verwaltet Ihre Organisation aus einer einzigen Binary heraus – eine Überprüfung, die früher das Durchklicken des Dashboards erforderte, ist jetzt eine einzige Zeile, die Sie erneut ausführen, als Alias anlegen oder in ein Runbook einfügen können. Sie erhalten vier Bereiche:
+
+- **Daten lesen:** `sessions`, `events`, `evals` und `errors`, gefiltert nach Zeit, Agent und Umgebung.
+- **Organisation verwalten:** `keys`, `users`, `settings`, `alerts` und `incidents`.
+- **Analysen ausführen:** gespeichertes SQL sowie ein Ad-hoc-`query`-Runner über Ihre Event-Daten.
+- **Den Assistenten befragen:** `agent ask` erreicht denselben schreibgeschützten Analysten, mit dem Sie im Dashboard chatten.
+
+Installieren Sie es einmalig mit `pipx`, melden Sie sich mit einem per E-Mail zugesandten 6-stelligen Code an, und Sie sind startklar. Die Sitzung dauert etwa einen Tag; führen Sie `agenteye login` erneut aus, wenn sie abläuft. Nutzen Sie es für schnelle Produktionsprüfungen, das Bereitstellen eines Schlüssels oder die Triage eines aktiven Vorfalls – alles ohne Browser:
+
+```bash
+agenteye errors --since 24h --aggregate      # what is breaking, grouped by error type
+agenteye incidents list --state firing       # what is on fire right now
+agenteye keys create ci --add events:add     # a key that can only push events, secret shown once
+```
+
+Eine wichtige Konvention: Globale Optionen wie `--json` stehen vor dem Befehl. `agenteye --json sessions` ist korrekt; `agenteye sessions --json` ist es nicht.
+
+## Skripte und CI-Integration
+
+Jeder Befehl akzeptiert `--json`, und das ändert alles. Sauberes JSON geht nach stdout, während Statusmeldungen und Warnungen für Menschen nach stderr gehen – ein `--json`-Output lässt sich also direkt in `jq` pipen, ohne störende Zeilen herausfiltern zu müssen. Das macht das CLI gleichermaßen nützlich für Sie an der Eingabeaufforderung und für einen Coding-Agenten, der die Ausgabe verarbeitet:
+
+```bash
+agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'
+```
+
+Es ist für den unbeaufsichtigten Betrieb ausgelegt. Bestätigungsabfragen werden automatisch übersprungen, wenn kein Terminal angebunden ist – nichts bleibt in einer Pipeline hängen –, und jeder Befehl gibt einen aussagekräftigen Exit-Code zurück: `0` Erfolg, `4` nicht eingeloggt, `5` fehlende Berechtigung (die Meldung nennt sie, z. B. `alerts:write`), `3` Dashboard nicht erreichbar. Ein Skript kann bei `4` eine erneute Authentifizierung einleiten oder bei `5` genau sagen, was bei einem Administrator anzufragen ist, anstatt ohne Rückmeldung zu scheitern.
+
+## Einen Coding-Agenten auf Englisch steuern lassen
+
+Noch besser: Sie sollten sich all diese Flags gar nicht merken müssen. Die **CLI-Skill** ist ein kleiner Agent-Skill-Ordner namens `agenteye-cli`, der einen Coding-Agenten wie Claude Code oder Codex beibringt, das CLI auf Basis von Anfragen in natürlicher Sprache zu bedienen. Fragen Sie „Ist heute etwas defekt?" und der Agent wählt den passenden Befehl, führt ihn in Ihrem Namen aus und antwortet in Prosa.
+
+Für Claude Code legen Sie den `agenteye-cli`-Ordner in `~/.claude/skills/` ab – er wird automatisch erkannt. Failproof AI Observability stellt den Ordner bereit; es ist nichts Zusätzliches zu installieren, da er nur das bereits installierte CLI steuert. Melden Sie sich zunächst selbst an: Die Skill kann den Login per E-Mail-Code nicht für Sie abschließen.
+
+Da der Agent das CLI unter Ihrer Identität ausführt, kann er alles tun, was Ihr Login erlaubt – Lesen und Schreiben gleichermaßen: Schlüssel erstellen, Einstellungen ändern, Vorfälle auflösen. Die „Sind Sie sicher?"-Abfrage des CLI wird für einen Agenten nicht ausgelöst, daher ist die Skill so gestaltet, dass sie den genauen Befehl nennt und auf Ihre Zustimmung wartet, bevor eine Änderung vorgenommen wird. Sie sind der Bestätigungsschritt.
+
+```text
+you    Why did session run-001 fail?
+
+agent  Running: agenteye --json events --session-id run-001 --all
+       The checkout-agent hit a TimeoutError on its third tool call.
+```
+
+Lesevorgänge bleiben sofort, und jeder Schreibvorgang wartet auf Sie:
+
+```text
+you    Give CI a key that can only push events.
+
+agent  This creates an API key. I'll run:
+         agenteye keys create ci --add events:add
+       OK to proceed?
+
+you    yes
+
+agent  Done. Key "ci" created with events:add only. The secret is shown once, so store it now.
+```
+
+## Weiterführendes
+
+- [CLI-Referenz](/de/agenteye/cli): Alle Befehle, Flags und JSON-Strukturen.
+- [CLI-Rezepte für Agenten](/de/agenteye/cli-recipes): Kopierfertige `jq`-Muster und Exit-Code-Behandlung.
+- [CLI-Agent-Skill](/de/agenteye/cli-skill): Installation und Verwendung der `agenteye-cli`-Skill.
+- [KI-Assistent](/de/agenteye/assistant): Der Dashboard-Analyst, mit dem `agent ask` kommuniziert.