# API-Authentifizierung

Wählen Sie OAuth oder eine bereichsbezogene Umgebungsvariablen-Übergabe entsprechend dem Client und der API-Oberfläche.

- Canonical: https://docs.xmemo.dev/de/docs/api/authentication
- Locale: de-DE
- Content-Locale: de-DE
- Canonical-Content-Digest: 2ccb101521e35878569be22c158ebf3f733f976c32f1b7952809dc29ffb5dba5
- Edition-Digest: 2f217ab8e0f93c92f665dec1d28813d7568298ff2f64759df3c2b3f306108650
- Source-Revision: sha256:0f4e5aaa7eba4f6a045f2818119002c0ddba188a30db4cee7ebfd8a2164d3e96

## Zwei authentifizierte Oberflächen

Der gehostete MCP-Endpunkt und die REST-API authentifizieren sich unterschiedlich. Wählen Sie den Ansatz, der zu dem von Ihnen angebundenen Client passt, und platzieren Sie niemals Anmeldedaten in einer öffentlichen Konfiguration oder einer generierten URL.

- MCP — OAuth, wo der Client es unterstützt, andernfalls Authorization: Bearer ${XMEMO_KEY}.
- REST-Datenebene — X-API-Key: <your-assigned-api-key> (Authorization: Bearer <token> wird vom Server ebenfalls akzeptiert). POST /v1/agents/temporary-register ermöglicht die anonyme Registrierung unter seinen Onboarding-Bedingungen und dem täglichen IP-Kontingent.
- Identitäts-Header dienen ausschließlich der Zuordnung und gewähren niemals Zugriff.

## Basis-URL

Setzen Sie BASE_URL auf den Ursprung des Deployments. Das gehostete Produkt verwendet https://xmemo.dev; das committete OpenAPI-Dokument deklariert zudem http://localhost:8000 für die lokale Entwicklung und https://api.memory-os.example.com als Beispielserver. REST-Aufrufe der Datenebene nutzen /v1-Pfade.

```bash
BASE_URL="${BASE_URL:-https://xmemo.dev}"
curl -sS "$BASE_URL/v1/recall?query=connection%20check&limit=1" \
  -H "X-API-Key: $XMEMO_KEY"
```

## REST-Authentifizierungs-Header

Die meisten REST-Anfragen übertragen den API-Schlüssel-Header. Anfragen ohne gültige Anmeldedaten werden abgelehnt, bevor Speicher gelesen oder geschrieben wird; POST /v1/agents/temporary-register ist die dokumentierte Ausnahme für die temporäre Registrierung. Ungültige vorgelegte Anmeldedaten werden abgelehnt.

```http
X-API-Key: <your-assigned-api-key>
```

## MCP-Authentifizierung

OAuth-Clients benötigen lediglich die gehostete Server-URL. Nicht verifizierte dynamische Clients müssen Speicher- und Wissensbereiche explizit anfordern; verifizierte Clients behalten den bestehenden Standard bei, wenn der Bereich weggelassen wird. Die Autorisierung gewährt nur die genehmigten Bereiche. Direkte und headless Clients lesen das Token stattdessen aus der Umgebung aus.

```json
{
  "servers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp"
    }
  }
}
```

## Berechtigungsbereiche (Scopes)

Der Server bewertet die Berechtigungsbereiche des Anmeldedatums und den angeforderten Speicherbereich unabhängig voneinander. Verwenden Sie memory:read für Abruf, Suche, Kontext, Auflistung und Projekt-Lesezugriffe; verwenden Sie memory:write für Schreibvorgänge und Mutationen. Wissensoperationen erfordern strikt knowledge:read und weisen memory:read-Token mit 403 ab. Fortgeschrittene direkte Token können engere Berechtigungen wie memory:update, memory:delete, memory:restore, memory:redact oder memory:hard_delete nutzen. Die Legacy-REST-Aliase read:memories und write:memories bleiben als Kompatibilitätswerte erhalten; Berechtigungsbereiche erweitern niemals die Autorisierung von Eigentümer, Team oder Token-Bereich.

- Lesen: memory:read.
- Schreiben: memory:write; Mutationsoperationen können eine engere Berechtigung erfordern, wenn das Token-Profil dies unterstützt.
- Wissen: knowledge:read; strikt erforderlich für die Suche und Auflistung von Wissensinhalten (memory:read-Token geben 403 zurück).
- Projekt-/Teamzugriff: Der Eigentümer des Tokens oder das gebundene Team und die aktive Rolle müssen zudem den angeforderten Bereich/team_id autorisieren.
- Zuordnungs-Header und Herkunftsfelder identifizieren einen Aufrufer; sie sind keine Berechtigungsbereiche und gewähren keinen Zugriff.

## Fehler-Schema

Die OpenAPI-Pfade deklarieren HTTPValidationError für die Anfragevalidierung (422) und belassen die meisten Antwortschemas ansonsten typlos. Der standardmäßige REST-Fehler bleibt ein JSON-Objekt mit einem detail-Wert. Erkannte Autorisierungsfehler können auch im RFC 9457-Stil als application/problem+json angefordert werden; verwenden Sie das Feld code für die maschinelle Verarbeitung statt Fließtext abzugleichen.

```json
{
  "detail": "invalid_token"
}

{
  "type": "urn:xmemo:problem:invalid_token",
  "title": "Invalid access token",
  "status": 401,
  "code": "invalid_token",
  "detail": "The presented access token is missing, expired, revoked, or otherwise invalid."
}
```

## Rate-Limits

OpenAPI veröffentlicht keine festen Rate-Limit-Kontingente. Die Laufzeitumgebung nutzt ein festes 60-Sekunden-Fenster, sofern aktiviert (außerhalb von Entwicklung/Lokal/Test standardmäßig aktiv): Die Kategorie der Datenebene umfasst 600 Anfragen pro Minute, Speicherschreibvorgänge nutzen eine Endpunkt-Richtlinie von 180 pro Minute und Speicher-Such-/Abruf-/Kontext-Lesezugriffe nutzen eine Endpunkt-Richtlinie von 300 pro Minute. Operatoren können diese Werte über die Umgebungsvariablen MEMORY_OS_RATE_LIMIT_* überschreiben; codieren Sie Kontingente nicht fest in einem Client.

- 429-Antwort: { detail: Rate limit exceeded, category, policy, limit, window_seconds, retry_after_seconds }.
- 429-Header: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset und X-RateLimit-Policy.
- Erfolgreiche Antworten legen ebenfalls die X-RateLimit-*-Header für Limit, Remaining, Reset und Policy offen, wenn die Drosselung aktiviert ist.