Skip to main content

​
Symptom

Anfragen an die Localmind-API schlagen fehl, obwohl ein API-Key hinterlegt ist. Typische Ausprägungen:
  • 401 Unauthorized — die Authentifizierung wird abgelehnt.
  • 403 Forbidden — die Aktion wird verweigert, obwohl der Schlüssel gültig ist.
  • 404 Not Found — eine Ressource, die nachweislich existiert (z. B. ein Agent oder Dokument), erscheint als nicht vorhanden.

​
Mögliche Ursachen

API-Keys sind in Localmind persönliche Schlüssel: Sie erstellen sie unter Benutzereinstellungen → API-Schlüssel, wählen als Scope „alle Spaces” oder „ausgewählte Spaces”, und jeder Schlüssel ist an Ihre Heimat-Organisation gebunden. Daraus ergeben sich die häufigsten Ursachen:
  • Der Schlüssel wurde widerrufen oder ist abgelaufen (das Ablaufdatum ist beim Erstellen konfigurierbar).
  • Der Schlüssel wurde falsch kopiert (z. B. mit führenden/nachfolgenden Leerzeichen oder Zeilenumbrüchen).
  • Der Schlüssel wird im falschen Header-Format übergeben.
  • Endpoint akzeptiert keine API-Keys: Nicht jeder Endpoint akzeptiert API-Keys — manche sind der Frontend-Session vorbehalten. Die API antwortet dann mit 401 und der Meldung „API key not accepted on this endpoint”.
  • Falscher Key-Scope: Der Schlüssel ist auf „ausgewählte Spaces” beschränkt und der angesprochene Space ist nicht dabei. Die API antwortet dann bewusst mit einem stillen 404 statt 403 — die Ressource erscheint als nicht vorhanden.
  • Fehlende Rolle: Ihre Rollen erlauben die Aktion nicht. Ein API-Key kann nie mehr, als seine Besitzerin oder sein Besitzer darf (Rollen-Narrowing) — die API antwortet mit 403.
  • Die Ressource liegt außerhalb Ihrer Heimat-Organisation — dort gilt der Schlüssel nicht.

​
Lösung

1

Status und Ablauf prüfen

Öffnen Sie Benutzereinstellungen → API-Schlüssel und prüfen Sie, ob der Schlüssel den Status „Aktiv” hat und nicht abgelaufen ist. Widerrufene Schlüssel können nicht reaktiviert werden — erstellen Sie in diesem Fall einen neuen.
2

Schlüssel erneut kopieren

Ein Schlüssel ist nach dem Erstellen nur einmalig im Klartext sichtbar. Wenn Sie sich beim Kopieren unsicher sind (Leerzeichen, Zeilenumbrüche), widerrufen Sie den Schlüssel und erstellen Sie einen neuen.
3

Key-Scope prüfen (bei 404)

Prüfen Sie, ob der Scope des Schlüssels den angesprochenen Space einschließt — „alle Spaces” oder der passende Eintrag unter „ausgewählte Spaces”. Ein Agent oder Dokument außerhalb des Key-Scopes liefert ein stilles 404, keine Berechtigungsfehlermeldung. Hintergründe: HTTP-Fehlercodes verstehen.
4

Rolle prüfen (bei 403)

Prüfen Sie, ob Ihre Rollen in Organisation und Space die Aktion erlauben. Der Schlüssel erweitert Ihre Rechte nicht — Details unter Authentifizierung und Rollen.
5

Header-Format prüfen

Der Schlüssel muss als Bearer-Token im Authorization-Header übergeben werden: Authorization: Bearer sk-...
Organisations-Admins können unter Einstellungen → Sicherheit → API-Schlüssel alle Schlüssel der Organisation einsehen und Schlüssel für andere Benutzer ausstellen. Wenden Sie sich an Ihren Admin, wenn Sie den Zustand eines Schlüssels nicht selbst klären können.
Erstellen Sie für verschiedene Integrationen separate API-Schlüssel mit aussagekräftigen Namen. So können Sie bei Problemen gezielt einzelne Schlüssel widerrufen, ohne andere Integrationen zu beeinträchtigen.

​
Nächste Schritte

HTTP-Fehlercodes verstehen

Was 422, 403 und das stille 404 bedeuten — und wie Sie sie beheben.

Persönliche API-Schlüssel

Schlüssel erstellen, Scope wählen, widerrufen — die vollständige Anleitung.