Skip to main content
Die Localmind API kennt zwei Authentifizierungsmethoden auf denselben Endpunkten. Diese Seite erklärt beide, grenzt sie vom separaten Automate-API-Key ab und beschreibt das zentrale Sicherheitsprinzip, das Admins kennen müssen: Ein API-Key kann Zugriff nur verengen, niemals erweitern.
Diese Seite ist für Entwickler (die programmatisch auf Localmind zugreifen) und für Admins (die verstehen wollen, welche Rechte ein ausgestellter Key hat) gleichermaßen relevant.

​
Die zwei Authentifizierungsmethoden

Beide Methoden senden ein Bearer-Token im Authorization-Header. Sie wirken auf denselben Endpunkten, unterscheiden sich aber in der Token-Quelle:
MethodeHeaderQuelleTypischer Einsatz
User-API-KeyAuthorization: Bearer sk-…In der Web-App erstellt (Benutzereinstellungen → API-Schlüssel)Programmatischer Zugriff: eigene Apps, n8n, OpenAI-SDK-Umstieg, RAG über eigene Dokumente
Keycloak-JWTAuthorization: Bearer <jwt>Frontend-Session der Web-AppDie Localmind-Web-App selbst
curl -X GET "https://<deine-instanz>-api.localmind.ai/v1/models" \
  -H "Authorization: Bearer sk-…"
Der User-API-Key ist die kanonische Methode für die programmatische Nutzung. Er gilt nur für die Heim-Organisation des Users, der ihn erstellt hat. Den Scope wählen Sie beim Anlegen: alle Spaces oder ausgewählte Spaces. Wie Sie einen Key in der Web-App anlegen und widerrufen, beschreibt die Plattform-Seite Persönliche API-Schlüssel.

​
Abgrenzung: der Automate-API-Key

Für die n8n-basierte Automate-Umgebung existiert ein separater API-Key mit einer anderen Header-Konvention:
Der Automate-API-Key wird im Header X-Api-Key gesendet und gilt ausschließlich für Automate-/n8n-Workflow-Endpunkte. Er ist nicht dasselbe wie der hier dokumentierte User-API-Key und funktioniert nicht auf den /v1-Endpunkten der Localmind API. Verwechseln Sie die beiden nicht.

​
Kernprinzip: Ein Key verengt, er erweitert nie

Ein User-API-Key hat exakt die Berechtigungen seines Besitzers — nicht mehr und nicht weniger. Er kann den Zugriff gegenüber dem Besitzer nur verengen (per Scope), niemals über dessen Rolle hinaus erweitern. Bei jeder Anfrage mit einem Key greifen drei Gates. Bei Keycloak-JWT sind diese Gates No-Ops, das Frontend-Verhalten bleibt unverändert.
GateWirkung
User-PermissionsEs gilt dieselbe Space- und Rollen-Prüfung wie im Frontend. Der Key sieht und darf genau das, was der Besitzer sieht und darf.
Org-BindingDer Key ist an eine Organisation gebunden (die Heim-Org des Besitzers). Fremde Organisationen sind unerreichbar.
Space-ScopeEin scoped Key erreicht nur die beim Anlegen gewählten Spaces. Ein org-weiter Key erreicht alles, was der Besitzer in seiner Org sieht.
Das Prinzip ist für Admins die wichtigste Aussage: Sie müssen einem ausgestellten Key keine eigenen Rechte zuweisen. Der Key kann strukturell nie mehr, als die Rolle des Besitzers erlaubt. Wer einem Key weniger Reichweite geben will, schränkt den Scope auf ausgewählte Spaces ein.

​
Rolle bestimmt die erlaubten Aktionen

Da der Key die Rolle des Besitzers 1:1 erbt, entscheidet die Space-Rolle, welche Aktionen erlaubt sind. Lesen, Suchen und Chatten funktionieren mit jeder Rolle. Schreibende Aktionen (Anlegen, Hochladen, Löschen) erfordern Schreibrechte im jeweiligen Space.
Rolle im SpaceLesen / Suchen / ChattenAnlegen / Upload / Löschen
Owner / Editor (z. B. eigener Privater Space)erlaubterlaubt — voller CRUD
Viewererlaubtabgelehnt mit 403
Ein Viewer-Key kann lesen und suchen, aber nicht schreiben. Eine Schreibanfrage wird mit einem 403 und einer sprechenden Meldung abgelehnt: 
{ "detail": "Permission denied: documents:create" }
Schreiben funktioniert nur in Spaces, in denen der Besitzer Schreibrechte hat. Der natürliche Ort dafür ist der eigene Private Space — jeder User ist dessen Owner und kann dort per Key alles verwalten. Die Rollenstruktur (Instanz → Org → Space) ist im Berechtigungsmodell und für die Org-Mitgliederverwaltung unter Mitglieder beschrieben.

​
Opt-in pro Endpunkt

Nicht jeder Endpunkt akzeptiert einen API-Key. Endpunkte, die nicht für den Key-Zugriff freigeschaltet sind, antworten bewusst mit 401 und verweisen auf die Frontend-Session: 
{ "detail": "API key not accepted on this endpoint. Use a Keycloak access token." }
Ein Beispiel ist GET /v1/me (Ihr eigenes Benutzerprofil): Mit einem User-API-Key liefert dieser Endpunkt absichtlich 401. Solche Endpunkte sind ausschließlich über eine Keycloak-Session erreichbar.

​
Narrowing ist wasserdicht

Das Scope-Modell verhindert Datenlecks über Filter. Ein Filter auf einen Space, den der Key nicht erreicht (fremder oder nicht-gescopter Space), liefert keinen Fehler, der Existenz verraten würde — er liefert 0 Treffer: 
curl -X POST "https://<deine-instanz>-api.localmind.ai/v1/data/hybrid-search" \
  -H "Authorization: Bearer sk-…" \
  -H "Content-Type: application/json" \
  -d '{"query": "Vertrag", "space_id": "<fremder-space>"}'
# -> 200 { "total_results": 0, "results": [] }
Fremde Spaces tauchen in POST /v1/spaces/search gar nicht erst auf. Der vom Aufrufer gesetzte Filter wird mit der für den Key erreichbaren Menge geschnitten, nie erweitert.

​
Nachvollziehbarkeit: Audit und last_used_at

Jede Key-Nutzung ist nachvollziehbar:
  • last_used_at wird bei jeder Anfrage aktualisiert.
  • Key-Aktionen werden im Audit-Log mit auth_method=api_key und der Key-ID attribuiert.
Diese Informationen sind in der Web-App einsehbar, aber nicht über den Key selbst auslesbar. Behandeln Sie API-Keys wie Passwörter: niemals in öffentlichen Repositories, Client-seitigem Code oder Logs ablegen. Bei Verdacht auf Kompromittierung widerrufen Sie den betroffenen Key gezielt, statt alle zu rotieren.

​
Verwandte Seiten

Konventionen und Fehler

Base-URL, Pagination, Filter-DSL, Fehlermodell und Statuscodes.

OpenAI-Kompatibel

GET /v1/models und POST /v1/chat/completions als Drop-in für OpenAI-SDKs.

Persönliche API-Schlüssel

Plattform-Sicht: Keys in der Web-App anlegen, scopen und widerrufen.

Org-Mitglieder verwalten

Admin-Sicht auf Mitglieder, deren Rollen und damit die Reichweite ihrer Keys.