Authentifizierung

Jede Anfrage wird authentifiziert mit einem Workspace API Schlüssel, als Bearer-Token gesendet:

Authorization: Bearer maetra_xxxxxxxxxxxxxxxxxxxx

Keys beginnen mit maetra_. Ein Schlüssel gehört zu einem Arbeitsbereich und trägt einen festen Satz von Geltungsbereiche. Der gleiche Schlüssel authentifiziert die REST API und die MCP Server.

Erstellen eines API-Schlüssels (im Dashboard)#

Öffnen Sie das Maetra-Dashboard und gehen Sie zu Einstellungen → API Keys.
Klicken API-Key erstellen.
Füllen Sie den Dialog aus:
- Schlüsselbezeichnung - ein Label, um es später zu erkennen, z.B. Production FinanceAgent.
- Zugangsbereiche — wählen Vollständiger Zugang, oder Zollrechtliche Geltungsbereiche pro Modul auswählen (Discover, Comply, Govern, Secure, Audit, Task Guard). Gewähren Sie den geringsten Schlüsselbedürfnissen - siehe Anwendungsbereiche unten.
- IP-Beschränkungen (fakultativ) Ein oder mehrere IPs/CIDR-Bereiche, aus denen der Schlüssel verwendet werden kann, z.B. 192.168.1.0/24.
Klicken Schaffen. Der vollständige Schlüssel wird angezeigt einmal — Treffer Kopierschlüssel, speichern Sie es in einem geheimen Manager, dann Ich habe meinen Schlüssel gespeichert.

Wichtig Maetra speichert nur einen Hash des Schlüssels und kann ihn nie wieder zeigen. Wenn ein Schlüssel verloren geht oder durchgesickert ist, Entziehen Sie es und erstellen Sie ein neues - Sie können es nicht wiederherstellen.

Anwendungsbereiche#

Scopes werden pro Anfrage überprüft. Ein Call Return 403 Forbidden wenn der Schlüssel gültig ist, aber der erforderliche Umfang fehlt.

Anwendungsbereich	Zuschüsse
`govern:checkpoints:write`	Checkpoints erstellen
`govern:checkpoints:read`	Lesen / Long-Poll Checkpoints
`govern:policies:read`	Aktive Politiken auflisten
`secure:scan:write`	Scan-Inhalte
`secure:rules:read`	Secure Regeln auflisten
`secure:rules:write`	Erstellen und Aktualisieren von Secure-Regeln
`secure:incidents:read`	Auflistung der Vorfälle
`discover:agents:read`	Liste der registrierten Agenten
`task_guard:tasks:write`	Starten, Aktualisieren, Anhalten, Fortsetzen, Abbrechen und Abschließen von Task Guard-Aufgaben
`task_guard:tasks:read`	Aktiver Task Guard Aufgabenkontext abrufen
`task_guard:checks:write`	Überprüfen Sie die Handlungsausrichtung und erklären Sie Aufgabenbeziehungen
`task_guard:effects:write`	Berichten und Vergleichen der tatsächlichen Wirkung
`task_guard:confirmations:write`	Senden Sie vertrauenswürdige Host-Benutzerereignisse und Umfangsbestätigungen

Wildcards

Ein Schlüssel kann Wildcard-Bereiche enthalten: * (alles) oder ein Modulpräfix wie govern:* / secure:* / discover:* / task_guard:*. Das Armaturenbrett Vollständiger Zugang Zuschüsse *; Auswahl eines ganzen Moduls unter Zollrechtliche Geltungsbereiche gewährt dieses Moduls *.

Anmerkung: task_guard:confirmations:write ist notwendig, aber nicht ausreichend für vertrauenswürdige Host-Events und Inline-Ergebnisse. Der API-Schlüssel muss auch als vertrauenswürdiger Task Guard-Bestätigungsnachweis für den Arbeitsbereich markiert werden.

Überprüfen Sie einen Schlüssel#

Verwendung GET /v1/ping um zu bestätigen, dass ein Schlüssel gültig ist und seine Anwendungsbereiche sehen:

curl "https://api.maetra.io/v1/ping" \
  -H "Authorization: Bearer $MAETRA_API_KEY"

{ "ok": true, "workspace_id": "ws_3Nf9k2", "scopes": ["govern:checkpoints:write"] }

Einen Schlüssel widerrufen#

Entziehen Sie einen Schlüssel von Einstellungen → API Keys (Aktionsmenü der Zeile). Widerruf ist sofort — weitere Anfragen Rückkehr 401 Unauthorized. Das Widerrufen eines Schlüssels hat nie Auswirkungen auf die anderen.

Siehe Fehler & Rate Limits für das vollständige Fehlerformat.