Authentifizierung & Mind Keys

Synapse verwendet zwei Authentifizierungsmethoden, jede für einen anderen Anwendungsfall optimiert. Den Unterschied zu verstehen ist essenziell für zuverlässige Integrationen.

Zwei Auth-Methoden

Mind Key (für Agenten)

Ein Mind Key ist ein Tenant-scoped API-Token. Er authentifiziert die Daten eines einzelnen Minds (Memories, Tasks, Chat, Scripts etc.). Verwende ihn für:

• LLM-Agenten, die die API aufrufen
• Hintergrund-Automatisierungs-Scripts
• MCP-Server-Konfiguration
• Jede langlebige Integration

Header-Authentifizierung (empfohlen)

curl -H "Authorization: Bearer mk_yourMindKeyHere" \
     https://synapse.schaefer.zone/memory/recall

Query-Parameter (für reine URL-Tools)

curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere

Einen Mind Key anlegen

curl -X POST https://synapse.schaefer.zone/minds \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Work Mind", "description": "Project memories"}'

Die Antwort enthält mind_key — sofort speichern, er wird nur einmal angezeigt.

Deine Minds auflisten

curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/minds

Einen Mind löschen (unumkehrbar!)

curl -X DELETE -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/minds/m_xyz789

JWT (für Menschen)

JWTs authentifizieren das Nutzerkonto, nicht einen spezifischen Mind. Verwende sie für:

• Konto-Registrierung und Login
• Minds anlegen / auflisten / löschen
• Minds mit anderen Nutzern teilen
• Web-Push-Abonnement-Verwaltung

Registrieren

curl -X POST https://synapse.schaefer.zone/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "secret"}'

Liefert: { "jwt": "eyJ...", "user": {...} }

Einloggen

curl -X POST https://synapse.schaefer.zone/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "secret"}'

Liefert: { "jwt": "eyJ...", "user": {...} }

JWT-Ablauf

JWTs laufen nach 7 Tagen ab. Wenn ein JWT abläuft, rufe einfach wieder /login auf, um ein frisches zu erhalten. Der Mind Key läuft nie ab, daher funktionieren bestehende Agent-Integrationen weiter.

Security-Best-Practices

Environment-Variablen-Pattern

# .env (NEVER commit this file)
SYNAPSE_MIND_KEY=mk_yourMindKeyHere
SYNAPSE_URL=https://synapse.schaefer.zone

// Node.js
const mindKey = process.env.SYNAPSE_MIND_KEY;
const url = process.env.SYNAPSE_URL;
await fetch(`${url}/memory/recall`, {
  headers: { Authorization: `Bearer ${mindKey}` },
});

MCP-Server-Config

{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["-y", "synapse-mcp-api@latest"],
      "env": {
        "SYNAPSE_MIND_KEY": "mk_yourMindKeyHere",
        "SYNAPSE_URL": "https://synapse.schaefer.zone"
      }
    }
  }
}

Multi-Mind-Pattern

Jeder Nutzer kann mehrere Minds haben. Häufige Patterns:

Verwende in verschiedenen LLM-Sessions unterschiedliche Mind Keys, um Kontexte getrennt zu halten.

Rate Limits

Rate-Limit-Header (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After) werden bei Bedarf in Antworten mitgeliefert.

Nächste Schritte

• Mind Key vs JWT — wann was verwenden
• Memory-API — was du mit einem Mind Key tun kannst
• User-API — Kontoverwaltung mit JWTs