# Autenticazione e Mind Key
SUMMARY: Come funziona l'autenticazione di Synapse: Mind Key per agenti, JWT per umani, ?key= disabilitato per impostazione predefinita (solo 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.

Autenticazione e Mind Key
Synapse usa due metodi di autenticazione, ciascuno ottimizzato per un caso
d'uso diverso. Comprendere la differenza è essenziale per costruire
integrazioni affidabili.
Due metodi di auth
| Metodo | Caso d'uso | Rate limit | Scadenza |
|--------|----------|------------|--------|
| Mind Key | Agenti LLM, strumenti automatizzati | 120/min (Bearer esterno); ?key= disabilitato per impostazione predefinita (deny) | Mai |
| JWT | UI human-facing, operazioni account | 120/min (IP esterni) | 7 giorni |
Mind Key (per agenti)
Una Mind Key è un token API con scope tenant. Autentica i dati di una singola
mente (memorie, attività, chat, script, ecc.). La usi per:
- Agenti LLM che chiamano l'API
- Script di automazione in background
- Configurazione del server MCP
- Qualsiasi integrazione long-lived
Autenticazione tramite header (consigliata)
[CODE BLOCK]
Parametro query (disabilitato per impostazione predefinita)
[CODE BLOCK]
> [!WARNING]
> Il parametro query  è disabilitato dal default indurito :
> il server risponde a  con 401 e il suggerimento "Query-param auth (?key=) is disabled". Solo Bearer è il default sicuro
> (SSOT: ). Solo se un operatore imposta esplicitamente ,
>  funziona come valvola di transizione con 60 req/min (per IP). I client Bearer esterni
> ottengono 120 req/min per identità; le reti interne affidabili non hanno limiti.
Creare una Mind Key
[CODE BLOCK]
La risposta include  — la salvi immediatamente, viene mostrata
una sola volta.
Elencare le sue menti
[CODE BLOCK]
Eliminare una mente (irreversibile!)
[CODE BLOCK]
JWT (per umani)
I JWT autenticano l'account utente, non una specifica mente. Li usi per:
- Registrazione e login dell'account
- Creare / elencare / eliminare menti
- Condividere menti con altri utenti
- Gestione delle sottoscrizioni Web Push
Registrazione
[CODE BLOCK]
Restituisce: 
Login
[CODE BLOCK]
Restituisce: 
Scadenza del JWT
I JWT scadono dopo 7 giorni. Quando un JWT scade, chiami semplicemente
 nuovamente per ottenerne uno nuovo. La Mind Key non scade mai, quindi
le integrazioni agente esistenti continuano a funzionare.
Best practice di sicurezza
> [!CRITICAL]
> - Non committi mai le Mind Key su git. Usi variabili di ambiente.
> - Non logghi mai le Mind Key. Le mascheri nei log ().
> - Roti le chiavi se sospetta una leak (elimini la mente, ne crei una nuova).
> - Usi una mente per progetto per limitare il raggio d'azione se una chiave leaka.
Modello con variabili di ambiente
[CODE BLOCK]
[CODE BLOCK]
Configurazione del server MCP
[CODE BLOCK]
Modello multi-mente
Ogni utente può avere menti multiple. Modelli comuni:
| Nome mente | Scopo |
|-----------|---------|
|  | Memorie relative al lavoro |
|  | Preferenze personali, famiglia |
|  | Contesto di progetto specifico |
|  | Avanzamento dell'apprendimento |
|  | Fallback generico |
Usi Mind Key diverse per sessioni LLM diverse per mantenere i contesti
isolati.
Limiti di traffico
| Metodo di auth | Limite | Ambito |
|-------------|-------|-------|
| Mind Key (header) | 120/min da IP esterni (per identità); illimitato per le reti interne affidabili | Per-mente |
| Mind Key (?key=, solo con allow) | 60/min | Per-IP |
| JWT (header) | 120 req/min (IP esterni; illimitato per le reti interne affidabili) | Per-utente |
| Endpoint pubblici | Nessuno | Globale |
Gli header di rate limit (, ,
) sono inclusi nelle risposte quando applicabile.
Prossimi passi
- Mind Key vs JWT — quando usare quale
- Memory API — cosa può fare con una Mind Key
- API User — gestione account con JWT