API Keys

​

Berechtigungen

Nicht an Keys zuweisbar. Zwei gültige Berechtigungen sind ausschließlich für Menschen/Dashboards vorgesehen und können keinem API Key gewährt werden: orgs:admin (Instanzverwaltung, die nur Operatoren vorbehalten ist) und keys:update. Eine Anfrage an POST /keys oder PATCH /keys/:id, die versucht, eine dieser beiden zu gewähren, wird mit HTTP 422 abgelehnt. Warum ein Bearer Key zwar Keys erstellen, sie aber nie bearbeiten darf, erläutert die Zeile keys:update weiter unten.

​

Events Ingest & Abfrage

​

Sessions & Evaluierungen

​

Dashboards

​

Gespeicherte Abfragen (SQL-Composer)

​

KI-Assistent

​

API Keys

​

Dashboard-Nutzer

​

Betriebseinstellungen

​

Alerts & Incidents

​

Audits

Als Audits eingeführt wurden, wurden bestehende Berechtigungsinhaber analog zu den Rollen bei Alerts erweitert: Jeder Nutzer und jedes Berechtigungs-Set mit alerts:read erhielt audits:read, und jeder Inhaber von alerts:write erhielt audits:write. Bestehende API Keys wurden nicht erweitert — weise einem Key audits:* explizit zu, wenn er die Audit-Oberfläche benötigt.

Gespeicherte Grants des veralteten alerts:ack-Tokens werden als incidents:ack interpretiert, damit On-Caller ohne Neuvergabe weiterhin Zugriff haben. Das Token ist im Dashboard-Nutzer-Editor nicht mehr zuweisbar; die Matrix bietet stattdessen incidents:ack an.

Der Empfänger-Picker-Endpunkt GET /alerts/recipients (der die Mitglieds-E-Mails auflistet, die ein Alert-Editor benachrichtigen kann) ist für Inhaber von entweder alerts:read oder alerts:write erreichbar, sodass Alert-Editoren den Picker 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). Weise dashboards:write zu, damit ein Nutzer Dashboards erstellen oder bearbeiten kann, und dashboards:delete, um sie zu löschen.

/health und /auth/* (OTP-Anfrage, OTP-Verifizierung, Session-Prüfung, Logout) sind konzeptionell nicht authentifiziert; sie bilden den Login-Flow und den Liveness-Probe. GET /access-granters erfordert einen gültigen Key, aber keine bestimmte Berechtigung, sodass jeder eingeloggte Nutzer sehen kann, welche Admins bei Zugriffsänderungen zu kontaktieren sind.

​

Berechtigungs-Sets

• DEFAULT_USER_PERMISSIONS (der Grant, der vorausgewählt ist, wenn ein Admin + neuer Nutzer öffnet) ist standardmäßig das standard-Set. Siehe Deployment.
• Das --set-Flag bei agenteye-orgctl (Operator-Mitgliederverwaltung) startet ein Mitglied aus einem benannten Set, das du dann mit --add / --remove feinjustierst. Siehe Tenant Management.

Wenn ein Set eine Berechtigung enthält, die nicht Key-zuweisbar ist (z. B. ein benutzerdefiniertes Set mit keys:update), lässt das Ableiten eines Keys aus diesem Set die nicht zuweisbaren Tokens weg; andernfalls würde der Server den Key mit HTTP 422 ablehnen. Für Dashboard-Nutzer gilt diese Einschränkung nicht.

​

Bootstrap-Admin-Key

​

Organisations-Scoping

​

Keys erstellen

​

Collector-Key (nur Ingest)

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"]
  }'

​

Dashboard-Key (nur Lesen)

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"]
  }'

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

​

Keys auflisten

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

​

Einen Key deaktivieren

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

​

Einen Key neu generieren

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

​

Key-Verwaltung im Dashboard

​

Empfohlenes Key-Layout

Assistenten-Key. Der Key des Assistenten wird vom Server automatisch bereitgestellt aus der Umgebungsvariable AGENT_API_KEY (dasselbe Secret, das der Agent als AGENTEYE_API_KEY präsentiert); es gibt keinen manuellen Key-Erstellungsschritt und keinen Admin-Key, der dabei involviert ist. Seine Berechtigungen sind im Quellcode fest verankert, sodass der Scope durch Fehlkonfiguration nicht erweitert werden kann: Lesen über Events, Evaluierungen und Dashboards, plus Dashboards-Write und Queries-Read/-Write/-Run für den Authoring-Flow von KI-gestützten Abfragen. Alle SQL-Anfragen laufen weiterhin über dieselbe schreibgeschützte Rolle und sql_guard-Prüfungen wie eine nutzerverfasste Abfrage, sodass dies die Authoring-Oberfläche erweitert, nicht die Datenoberfläche; destruktive Operationen (queries:delete, dashboards:delete) bleiben absichtlich 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-Nutzer benötigen zusätzlich die Berechtigung agent:use, um den Assistenten zu sehen und zu verwenden. Wenn du die Selbstinstrumentierung aktivierst, gib dem Assistenten einen separaten Key mit nur events:add.