Mind Key vs JWT — Wann Was?

Synapse hat zwei Authentifizierungs-Tokens. Die falsche Wahl führt zu 401-Fehlern. Dieser Guide gibt dir einen klaren Entscheidungsrahmen.

Schnelle Entscheidungs-Tabelle

Die einfache Regel

Mind Key — Datenzugriffs-Token

Ein Mind Key gewährt Zugriff auf die Daten eines Minds. Er ist ein langlebiges Token, das nie abläuft (bis der Mind gelöscht wird). Perfekt für:

• LLM-Agenten, die Memories über Sessions persistieren
• Hintergrund-Cron-Jobs
• MCP-Server-Konfiguration
• Webhook-Integrationen
• Mobile Apps, die Memory lesen

Was der Mind Key kann

• GET /memory/recall — alle Memories in diesem Mind lesen
• POST /memory — Memories speichern/aktualisieren
• GET /chat/poll — Chat-Nachrichten lesen
• POST /chat/reply — Chat-Nachrichten senden
• GET /mind/tasks — Tasks auflisten
• POST /mind/task — Tasks anlegen
• POST /script — Scripts speichern
• POST /webhooks — Webhooks registrieren
• POST /computers/:id/commands — Computer-Commands einreihen

Was der Mind Key NICHT kann

• Minds anlegen / auflisten / löschen (braucht JWT)
• Mind mit anderem Nutzer teilen (braucht JWT)
• Nutzerkonto-Infos ansehen (braucht JWT)
• Web-Push abonnieren (braucht JWT)

JWT — Kontoverwaltungs-Token

Ein JWT authentifiziert das Nutzerkonto. Es läuft nach 7 Tagen ab und wird für Konto-Ebene-Operationen verwendet, die mehrere Minds umfassen oder andere Nutzer involvieren.

Was das JWT kann

• POST /minds — neuen Mind anlegen (liefert neuen Mind Key)
• GET /minds — alle Minds dieses Nutzers auflisten
• DELETE /minds/:id — Mind löschen
• POST /sharing — Mind mit anderem Nutzer teilen
• POST /push/subscribe — Web-Push-Benachrichtigungen abonnieren
• GET /sharing — Mind-Shares auflisten

Was das JWT NICHT kann

• Memories lesen / schreiben (braucht Mind Key)
• Chat-Nachrichten senden (braucht Mind Key)
• Tasks verwalten (braucht Mind Key)
• Webhooks registrieren (braucht Mind Key)

Sonderfall: Computer-Token

Die /computers/me/*-Endpunkte (agentenseitig, für den screen-remote-agent) verwenden einen dritten Token-Typ: das Computer-Token. Dieses Token wird von POST /computers/register beim Einlösen eines Installationscodes zurückgegeben und ist spezifisch für einen registrierten Rechner.

Häufige Patterns

Pattern 1: Einzelner LLM-Agent

1. Einmal registrieren → JWT erhalten
2. Einen Mind anlegen → Mind Key erhalten
3. LLM verwendet Mind Key für alles

Pattern 2: Multi-Projekt-Agent

1. Einmal registrieren → JWT erhalten
2. Mehrere Minds anlegen (work, personal, project-x) → mehrere Mind Keys erhalten
3. LLM lädt je nach Kontext unterschiedlichen Mind Key

Pattern 3: Team-Sharing

1. Nutzer A legt Mind an → Mind Key A erhalten
2. Nutzer A teilt mit Nutzer B via JWT (POST /sharing)
3. Nutzer B kann nun über sein eigenes JWT zugreifen
4. Für LLM-Zugriff muss Nutzer B einen eigenen Mind Key anlegen (oder A's verwenden)

Pattern 4: MCP-Server

MCP-Server verwenden immer Mind Key (via SYNAPSE_MIND_KEY-Env-Var gesetzt). Eine MCP-Server-Instanz = ein Mind. Für Multi-Mind-Zugriff: mehrere MCP- Instanzen betreiben oder Client-seitiges Mind-Switching implementieren.

Token-Format-Spickzettel

Nächste Schritte

• Authentifizierung — vollständiger Auth-Guide
• User- & Minds-API — JWT-geschützte Endpunkte
• Memory-API — Mind-Key-geschützte Endpunkte