API Keys

​

Die 3 Keys, die die meisten Deployments benötigen

​

Berechtigungen

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

​

Sessions & Evaluierungen

​

Dashboards

​

Gespeicherte Abfragen (SQL-Composer)

​

KI-Assistent

​

API-Keys

​

Dashboard-Benutzer

​

Betriebliche Einstellungen

​

Alarme & Vorfälle

​

Audits

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.

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

• 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

​

Organisations-Scoping

​

Keys erstellen

​

Collector-Key (nur Ingest)

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)

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

{
  "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/keys \
  -H "Authorization: Bearer $ADMIN_KEY"

​

Einen Key deaktivieren

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

​

Einen Key neu generieren

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

​

Key-Verwaltung im Dashboard

​

Empfohlenes Key-Layout

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

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: Wie Ihr Agent-Code sich beim Senden von Events authentifiziert.
• Security: Wie Anmeldung, Zugriffskontrolle und organisationsweite Datenisolierung funktionieren.