# Autenticazione e Mind Key
SUMMARY: Come funziona l'autenticazione di Synapse: Mind Key per agenti, JWT per umani, ?key= per strumenti solo-URL.

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 (60 req/min limit on query)
JWT: Authorization: Bearer eyJ... (no rate limit, 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 | Nessuno (header) / 60 min (query) | Mai |
| JWT | UI human-facing, operazioni account | Nessuno | 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 (per strumenti solo-URL)
[CODE BLOCK]
> [!WARNING]
> Il parametro query  è limitato a 60 richieste al minuto.
> L'header Bearer non ha rate limit. Usi l'header quando il suo client
> supporta header personalizzati.
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) | Nessuno | Per-mente |
| Mind Key (?key=) | 60/min | Per-IP |
| JWT (header) | Nessuno | 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