# Mind Key vs JWT — quando usare quale?
SUMMARY: Guida decisionale: Mind Key per accesso dati agente, JWT per gestione account.

KEY CONTEXT:
Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.
JWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.
Simple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.
Exception: /computers/me/* uses Computer Token (not Mind Key or JWT).

Mind Key vs JWT — quando usare quale?
Synapse ha due token di autenticazione. Scegliere quello sbagliato porta a
errori 401. Questa guida le dà un framework decisionale chiaro.
Tabella decisionale rapida
| Vuole... | Usi |
|----------------|-----|
| Memorizzare / richiamare memorie | Mind Key |
| Inviare / polling messaggi chat | Mind Key |
| Gestire attività | Mind Key |
| Memorizzare script | Mind Key |
| Registrare webhook | Mind Key |
| Controllare computer | Mind Key (lato utente) / Computer Token (lato agente) |
| Registrare un account utente | Nessuna (pubblico) |
| Login | Nessuna (pubblico) |
| Creare / elencare / eliminare menti | JWT |
| Condividere una mente con un altro utente | JWT |
| Sottoscrivere notifiche web push | JWT |
| Vedere il log di audit | Mind Key |
La regola semplice
> [!TIP]
> Se tocca i dati di una singola mente → Mind Key.
> Se gestisce l'account o i metadati delle menti → JWT.
Mind Key — token di accesso ai dati
Una Mind Key concede accesso ai dati di una mente. È un token long-lived
che non scade mai (fino a quando la mente viene eliminata). Perfetta per:
- Agenti LLM che persistono memorie tra sessioni
- Cron job in background
- Configurazione del server MCP
- Integrazioni webhook
- App mobile che leggono la memoria
Cosa può fare la Mind Key
-  — leggere tutte le memorie in questa mente
-  — memorizzare/aggiornare memorie
-  — leggere i messaggi chat
-  — inviare messaggi chat
-  — elencare le attività
-  — creare attività
-  — memorizzare script
-  — registrare webhook
-  — accodare comandi per computer
Cosa NON può fare la Mind Key
- Creare / elencare / eliminare menti (serve JWT)
- Condividere una mente con un altro utente (serve JWT)
- Vedere le informazioni dell'account utente (serve JWT)
- Sottoscrivere web push (serve JWT)
JWT — token di gestione account
Un JWT autentica l'account utente. Scade dopo 7 giorni ed è usato per
operazioni a livello di account che coprono più menti o coinvolgono altri
utenti.
Cosa può fare il JWT
-  — creare una nuova mente (restituisce una nuova Mind Key)
-  — elencare tutte le menti di questo utente
-  — eliminare una mente
-  — condividere una mente con un altro utente
-  — sottoscrivere notifiche web push
-  — elencare le condivisioni delle menti
Cosa NON può fare il JWT
- Leggere / scrivere memorie (serve Mind Key)
- Inviare messaggi chat (serve Mind Key)
- Gestire attività (serve Mind Key)
- Registrare webhook (serve Mind Key)
Caso speciale: Computer Token
Gli endpoint  (lato agente, per lo screen-remote-agent) usano
un terzo tipo di token: il Computer Token. Questo token viene restituito da
 quando si riscatta un codice di installazione, ed è
specifico per un computer registrato.
| Endpoint | Auth |
|----------|------|
|  | Computer Token |
|  | Computer Token |
|  | Mind Key o JWT |
|  | Mind Key o JWT |
Modelli comuni
Modello 1: agente LLM singolo
1. Si registra una volta → ottiene JWT
2. Crea una mente → ottiene Mind Key
3. L'LLM usa la Mind Key per tutto
Modello 2: agente multi-progetto
1. Si registra una volta → ottiene JWT
2. Crea menti multiple (work, personal, project-x) → ottiene Mind Key multiple
3. L'LLM carica Mind Key diverse in base al contesto
Modello 3: condivisione di team
1. L'Utente A crea una mente → ottiene Mind Key A
2. L'Utente A condivide con l'Utente B tramite JWT ()
3. L'Utente B ora può accedere tramite il suo stesso JWT
4. Per l'accesso LLM, l'Utente B deve creare la sua Mind Key (o usare quella di A)
Modello 4: server MCP
I server MCP usano sempre la Mind Key (impostata tramite variabile env
). Un'istanza del server MCP = una mente. Per accesso
multi-mente, esegua più istanze MCP o implementi cambio mente lato client.
Sintesi dei formati dei token
| Token | Formato | Esempio |
|-------|--------|---------|
| Mind Key |  + 36 caratteri |  |
| JWT |  + base64 |  |
| Computer Token |  + 36 caratteri |  |
Prossimi passi
- Autenticazione — guida auth completa
- User & Minds API — endpoint protetti da JWT
- Memory API — endpoint protetti da Mind Key