> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localmind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API-Key funktioniert nicht: 401, 403 oder stilles 404

> Anfragen mit dem API-Key werden abgelehnt, liefern Berechtigungsfehler oder finden vorhandene Ressourcen nicht.

## 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

<Steps>
  <Step title="Status und Ablauf prüfen">
    Öffnen Sie [Benutzereinstellungen → API-Schlüssel](/navigation/Persönliche-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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](/troubleshooting/HTTP-Fehlercodes).
  </Step>

  <Step title="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](/api-reference/Authentifizierung-und-Rollen).
  </Step>

  <Step title="Header-Format prüfen">
    Der Schlüssel muss als Bearer-Token im `Authorization`-Header übergeben werden: `Authorization: Bearer sk-...`
  </Step>
</Steps>

<Note>
  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.
</Note>

<Tip>
  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.
</Tip>

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="HTTP-Fehlercodes verstehen" icon="circle-alert" href="/troubleshooting/HTTP-Fehlercodes">
    Was 422, 403 und das stille 404 bedeuten — und wie Sie sie beheben.
  </Card>

  <Card title="Persönliche API-Schlüssel" icon="key" href="/navigation/Persönliche-API-Schlüssel">
    Schlüssel erstellen, Scope wählen, widerrufen — die vollständige Anleitung.
  </Card>
</CardGroup>