# Authenticatie & Mind Keys
SUMMARY: Hoe Synapse-authenticatie werkt: Mind Keys voor agents, JWT's voor mensen, ?key= standaard uitgeschakeld (alleen Bearer, AUTH_QUERY_KEY_MODE=deny).

KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx (?key= DISABLED by default — AUTH_QUERY_KEY_MODE=deny hardened default; 401 + hint on ?key=)
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.

Authenticatie & Mind Keys
Synapse gebruikt twee authenticatiemethoden, elk geoptimaliseerd voor een ander doel.
Het verschil begrijpen is essentieel voor het bouwen van betrouwbare integraties.
Twee auth-methoden
| Methode | Gebruik | Ratelimit | Verval |
|---------|---------|-----------|--------|
| Mind Key | LLM-agents, geautomatiseerde tools | 120/min (externe Bearer); ?key= standaard uitgeschakeld (deny) | Nooit |
| JWT | Mensgerichte UI, account-operaties | 120/min (externe IP's) | 7 dagen |
Mind Key (voor agents)
Een Mind Key is een tenant-scoped API-token. Het authenticeert de data van één mind
(herinneringen, taken, chat, scripts, enz.). Gebruik het voor:
- LLM-agents die de API aanroepen
- Achtergrond-automatiseringsscripts
- MCP-server-configuratie
- Elke langlevende integratie
Header-authenticatie (aanbevolen)
[CODE BLOCK]
Queryparameter (standaard uitgeschakeld)
[CODE BLOCK]
> [!WARNING]
> De -queryparameter is uitgeschakeld door de geharde standaardwaarde
> : de server antwoordt op  met 401 en de hint "Query-param auth (?key=) is disabled".
> Alleen Bearer is de veilige standaard (SSOT: ). Alleen als een operator
> expliciet  instelt, werkt  als overgangsklep met 60 req/min
> (per IP). Externe Bearer-clients krijgen 120 req/min per identiteit; vertrouwde interne
> netwerken zijn onbeperkt.
Een Mind Key aanmaken
[CODE BLOCK]
De respons bevat  — sla deze onmiddellijk op, deze wordt slechts één keer getoond.
Uw minds tonen
[CODE BLOCK]
Een mind verwijderen (onomkeerbaar!)
[CODE BLOCK]
JWT (voor mensen)
JWT's authenticeren het gebruikersaccount, niet een specifieke mind. Gebruik ze voor:
- Accountregistratie en login
- Minds aanmaken/tonen/verwijderen
- Minds delen met andere gebruikers
- Web Push-abonnementsbeheer
Registreren
[CODE BLOCK]
Retourneert: 
Inloggen
[CODE BLOCK]
Retourneert: 
JWT-verval
JWT's vervallen na 7 dagen. Wanneer een JWT vervalt, roept u gewoon opnieuw 
aan om een verse te krijgen. De Mind Key vervalt nooit, dus bestaande agent-integraties
blijven werken.
Beveiligings-best-practices
> [!CRITICAL]
> - Commit Mind Keys nooit naar git. Gebruik omgevingsvariabelen.
> - Log Mind Keys nooit. Maskeer ze in logs ().
> - Roteer sleutels bij vermoeden van een lek (verwijder de mind, maak een nieuwe aan).
> - Gebruik één mind per project om de schade bij een lek te beperken.
Omgevingsvariabele-patroon
[CODE BLOCK]
[CODE BLOCK]
MCP-server-config
[CODE BLOCK]
Multi-mind-patroon
Elke gebruiker kan meerdere minds hebben. Veelvoorkomende patronen:
| Mind-naam | Doel |
|-----------|------|
|  | Werkgerelateerde herinneringen |
|  | Persoonlijke voorkeuren, familie |
|  | Specifieke projectcontext |
|  | Leervoortgang |
|  | Algemene fallback |
Gebruik verschillende Mind Keys voor verschillende LLM-sessies om contexten gescheiden te houden.
Ratelimits
| Auth-methode | Limiet | Bereik |
|--------------|--------|--------|
| Mind Key (header) | 120/min vanaf externe IP's (per identiteit); onbeperkt voor vertrouwde interne netwerken | Per-mind |
| Mind Key (?key=, alleen met allow) | 60/min | Per-IP |
| JWT (header) | 120 req/min (externe IP's; onbeperkt voor vertrouwde interne netwerken) | Per-gebruiker |
| Openbare eindpunten | Geen | Globaal |
Ratelimit-headers (, , )
worden in responsen opgenomen waar van toepassing.
Volgende stappen
- Mind Key vs JWT — wanneer welke gebruiken
- Memory API — wat u kunt doen met een Mind Key
- User API — accountbeheer met JWT's