# Authentifizierung & Mind Keys
SUMMARY: Wie die Synapse-Authentifizierung funktioniert: Mind Keys für Agenten, JWTs für Menschen, ?key= als veralteter Rückfall für reine URL-Tools.

KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (query path deprecated, 60 req/min, AUTH_QUERY_KEY_MODE)
JWT: Authorization: Bearer eyJ... (120 req/min external IPs, unlimited internal; used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.

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
| Methode | Anwendungsfall | Rate Limit | Ablauf |
|---------|----------------|------------|--------|
| Mind Key | LLM-Agenten, automatisierte Tools | 120/min (externer Bearer) / 60/min (?key=, veraltet) | Nie |
| JWT | Human-UI, Konto-Operationen | 120/Min (externe IPs) | 7 Tage |
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)
[CODE BLOCK]
Query-Parameter (veralteter Rückfall für reine URL-Tools)
[CODE BLOCK]
> [!WARNING]
> Der -Query-Parameter ist veraltet und auf 60 Requests pro
> Minute begrenzt (gesteuert über ;  macht die
> API Bearer-only). Externe Bearer-Clients erhalten 120 req/min pro Identity,
> vertrauenswürdige interne Netze sind unbegrenzt. Verwende den Header, wenn
> dein Client eigene Header unterstützt.
Einen Mind Key anlegen
[CODE BLOCK]
Die Antwort enthält  — sofort speichern, er wird nur einmal
angezeigt.
Deine Minds auflisten
[CODE BLOCK]
Einen Mind löschen (unumkehrbar!)
[CODE BLOCK]
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
[CODE BLOCK]
Liefert: 
Einloggen
[CODE BLOCK]
Liefert: 
JWT-Ablauf
JWTs laufen nach 7 Tagen ab. Wenn ein JWT abläuft, rufe einfach wieder
 auf, um ein frisches zu erhalten. Der Mind Key läuft nie ab, daher
funktionieren bestehende Agent-Integrationen weiter.
Security-Best-Practices
> [!CRITICAL]
> - Mind Keys niemals in Git committen. Verwende Environment-Variablen.
> - Mind Keys niemals loggen. In Logs maskieren ().
> - Keys rotieren bei Verdacht auf Leak (Mind löschen, neuen anlegen).
> - Ein Mind pro Projekt, um den Schadensradius bei geleaktem Key zu begrenzen.
Environment-Variablen-Pattern
[CODE BLOCK]
[CODE BLOCK]
MCP-Server-Config
[CODE BLOCK]
Multi-Mind-Pattern
Jeder Nutzer kann mehrere Minds haben. Häufige Patterns:
| Mind-Name | Zweck |
|-----------|-------|
|  | Job-bezogene Memories |
|  | Persönliche Präferenzen, Familie |
|  | Spezifischer Projekt-Kontext |
|  | Lernfortschritt |
|  | Allzweck-Fallback |
Verwende in verschiedenen LLM-Sessions unterschiedliche Mind Keys, um Kontexte
getrennt zu halten.
Rate Limits
| Auth-Methode | Limit | Scope |
|---------------|-------|-------|
| Mind Key (Header) | 120/min externe IPs (pro Identity); unbegrenzt für vertrauenswürdige interne Netze | Pro-Mind |
| Mind Key (?key=, veraltet) | 60/min | Pro-IP |
| JWT (Header) | 120 Anf./Min (externe IPs; unbegrenzt für vertrauenswürdige interne Netzwerke) | Pro-Nutzer |
| Öffentliche Endpunkte | Keins | Global |
Rate-Limit-Header (, , )
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