{"title":"Autenticazione e Mind Key","slug":"authentication","category":"getting-started","summary":"Come funziona l'autenticazione di Synapse: Mind Key per agenti, JWT per umani, ?key= per strumenti solo-URL.","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":508,"read_minutes":3,"llm_context":"Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).\nMind Key: Authorization: Bearer mk_xxx OR ?key=mk_xxx (60 req/min limit on query)\nJWT: Authorization: Bearer eyJ... (no rate limit, used for /register, /login, /minds, /sharing)\nMind Key is shown only once at creation. Store it permanently.\nEach mind has exactly one Mind Key. Multiple minds = multiple keys.\n","lang":"it","translated":true,"requested_lang":"it","content_markdown":"\n# Autenticazione e Mind Key\n\nSynapse usa due metodi di autenticazione, ciascuno ottimizzato per un caso\nd'uso diverso. Comprendere la differenza è essenziale per costruire\nintegrazioni affidabili.\n\n## Due metodi di auth\n\n| Metodo | Caso d'uso | Rate limit | Scadenza |\n|--------|----------|------------|--------|\n| **Mind Key** | Agenti LLM, strumenti automatizzati | Nessuno (header) / 60 min (query) | Mai |\n| **JWT** | UI human-facing, operazioni account | Nessuno | 7 giorni |\n\n## Mind Key (per agenti)\n\nUna Mind Key è un token API con scope tenant. Autentica i dati di una singola\nmente (memorie, attività, chat, script, ecc.). La usi per:\n\n- Agenti LLM che chiamano l'API\n- Script di automazione in background\n- Configurazione del server MCP\n- Qualsiasi integrazione long-lived\n\n### Autenticazione tramite header (consigliata)\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n### Parametro query (per strumenti solo-URL)\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> Il parametro query `?key=` è limitato a **60 richieste al minuto**.\n> L'header Bearer non ha rate limit. Usi l'header quando il suo client\n> supporta header personalizzati.\n\n### Creare una Mind Key\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/minds \\\n -H \"Authorization: Bearer YOUR_JWT\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"name\": \"Work Mind\", \"description\": \"Project memories\"}'\n```\n\nLa risposta include `mind_key` — **la salvi immediatamente**, viene mostrata\nuna sola volta.\n\n### Elencare le sue menti\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds\n```\n\n### Eliminare una mente (irreversibile!)\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT (per umani)\n\nI JWT autenticano l'**account utente**, non una specifica mente. Li usi per:\n\n- Registrazione e login dell'account\n- Creare / elencare / eliminare menti\n- Condividere menti con altri utenti\n- Gestione delle sottoscrizioni Web Push\n\n### Registrazione\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/register \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"password\": \"secret\"}'\n```\n\nRestituisce: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Login\n\n```bash\ncurl -X POST https://synapse.schaefer.zone/login \\\n -H \"Content-Type: application/json\" \\\n -d '{\"email\": \"you@example.com\", \"password\": \"secret\"}'\n```\n\nRestituisce: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Scadenza del JWT\n\nI JWT scadono dopo **7 giorni**. Quando un JWT scade, chiami semplicemente\n`/login` nuovamente per ottenerne uno nuovo. La Mind Key non scade mai, quindi\nle integrazioni agente esistenti continuano a funzionare.\n\n## Best practice di sicurezza\n\n> [!CRITICAL]\n> - **Non committi mai le Mind Key su git.** Usi variabili di ambiente.\n> - **Non logghi mai le Mind Key.** Le mascheri nei log (`mk_***...***xyz`).\n> - **Roti le chiavi** se sospetta una leak (elimini la mente, ne crei una nuova).\n> - **Usi una mente per progetto** per limitare il raggio d'azione se una chiave leaka.\n\n### Modello con variabili di ambiente\n\n```bash\n# .env (NEVER commit this file)\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone\n```\n\n```typescript\n// Node.js\nconst mindKey = process.env.SYNAPSE_MIND_KEY;\nconst url = process.env.SYNAPSE_URL;\nawait fetch(`${url}/memory/recall`, {\n headers: { Authorization: `Bearer ${mindKey}` },\n});\n```\n\n### Configurazione del server MCP\n\n```json\n{\n \"mcpServers\": {\n \"synapse\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"synapse-mcp-api@latest\"],\n \"env\": {\n \"SYNAPSE_MIND_KEY\": \"mk_yourMindKeyHere\",\n \"SYNAPSE_URL\": \"https://synapse.schaefer.zone\"\n }\n }\n }\n}\n```\n\n## Modello multi-mente\n\nOgni utente può avere menti multiple. Modelli comuni:\n\n| Nome mente | Scopo |\n|-----------|---------|\n| `work` | Memorie relative al lavoro |\n| `personal` | Preferenze personali, famiglia |\n| `project-synapse` | Contesto di progetto specifico |\n| `learning-german` | Avanzamento dell'apprendimento |\n| `assistant-default` | Fallback generico |\n\nUsi Mind Key diverse per sessioni LLM diverse per mantenere i contesti\nisolati.\n\n## Limiti di traffico\n\n| Metodo di auth | Limite | Ambito |\n|-------------|-------|-------|\n| Mind Key (header) | Nessuno | Per-mente |\n| Mind Key (?key=) | 60/min | Per-IP |\n| JWT (header) | Nessuno | Per-utente |\n| Endpoint pubblici | Nessuno | Globale |\n\nGli header di rate limit (`X-RateLimit-Limit`, `X-RateLimit-Remaining`,\n`Retry-After`) sono inclusi nelle risposte quando applicabile.\n\n## Prossimi passi\n\n- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — quando usare quale\n- [Memory API](/docs/api/memory) — cosa può fare con una Mind Key\n- [API User](/docs/api/user) — gestione account con JWT\n","content_html":"

Autenticazione e Mind Key

\n

Synapse usa due metodi di autenticazione, ciascuno ottimizzato per un caso\nd'uso diverso. Comprendere la differenza è essenziale per costruire\nintegrazioni affidabili.

\n

Due metodi di auth

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
MetodoCaso d'usoRate limitScadenza
Mind KeyAgenti LLM, strumenti automatizzatiNessuno (header) / 60 min (query)Mai
JWTUI human-facing, operazioni accountNessuno7 giorni
\n

Mind Key (per agenti)

\n

Una Mind Key è un token API con scope tenant. Autentica i dati di una singola\nmente (memorie, attività, chat, script, ecc.). La usi per:

\n\n

Autenticazione tramite header (consigliata)

\n
curl -H "Authorization: Bearer mk_yourMindKeyHere" \\\n     https://synapse.schaefer.zone/memory/recall

Parametro query (per strumenti solo-URL)

\n
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
Il parametro query `?key=` è limitato a **60 richieste al minuto**.\nL'header Bearer non ha rate limit. Usi l'header quando il suo client\nsupporta header personalizzati.

Creare una Mind Key

\n
curl -X POST https://synapse.schaefer.zone/minds \\\n  -H "Authorization: Bearer YOUR_JWT" \\\n  -H "Content-Type: application/json" \\\n  -d '{"name": "Work Mind", "description": "Project memories"}'

La risposta include mind_key — la salvi immediatamente, viene mostrata\nuna sola volta.

\n

Elencare le sue menti

\n
curl -H "Authorization: Bearer YOUR_JWT" \\\n     https://synapse.schaefer.zone/minds

Eliminare una mente (irreversibile!)

\n
curl -X DELETE -H "Authorization: Bearer YOUR_JWT" \\\n     https://synapse.schaefer.zone/minds/m_xyz789

JWT (per umani)

\n

I JWT autenticano l'account utente, non una specifica mente. Li usi per:

\n\n

Registrazione

\n
curl -X POST https://synapse.schaefer.zone/register \\\n  -H "Content-Type: application/json" \\\n  -d '{"email": "you@example.com", "password": "secret"}'

Restituisce: { "jwt": "eyJ...", "user": {...} }

\n

Login

\n
curl -X POST https://synapse.schaefer.zone/login \\\n  -H "Content-Type: application/json" \\\n  -d '{"email": "you@example.com", "password": "secret"}'

Restituisce: { "jwt": "eyJ...", "user": {...} }

\n

Scadenza del JWT

\n

I JWT scadono dopo 7 giorni. Quando un JWT scade, chiami semplicemente\n/login nuovamente per ottenerne uno nuovo. La Mind Key non scade mai, quindi\nle integrazioni agente esistenti continuano a funzionare.

\n

Best practice di sicurezza

\n

Modello con variabili di ambiente

\n
# .env (NEVER commit this file)\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone
// Node.js\nconst mindKey = process.env.SYNAPSE_MIND_KEY;\nconst url = process.env.SYNAPSE_URL;\nawait fetch(`${url}/memory/recall`, {\n  headers: { Authorization: `Bearer ${mindKey}` },\n});

Configurazione del server MCP

\n
{\n  "mcpServers": {\n    "synapse": {\n      "command": "npx",\n      "args": ["-y", "synapse-mcp-api@latest"],\n      "env": {\n        "SYNAPSE_MIND_KEY": "mk_yourMindKeyHere",\n        "SYNAPSE_URL": "https://synapse.schaefer.zone"\n      }\n    }\n  }\n}

Modello multi-mente

\n

Ogni utente può avere menti multiple. Modelli comuni:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Nome menteScopo
workMemorie relative al lavoro
personalPreferenze personali, famiglia
project-synapseContesto di progetto specifico
learning-germanAvanzamento dell'apprendimento
assistant-defaultFallback generico
\n

Usi Mind Key diverse per sessioni LLM diverse per mantenere i contesti\nisolati.

\n

Limiti di traffico

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Metodo di authLimiteAmbito
Mind Key (header)NessunoPer-mente
Mind Key (?key=)60/minPer-IP
JWT (header)NessunoPer-utente
Endpoint pubbliciNessunoGlobale
\n

Gli header di rate limit (X-RateLimit-Limit, X-RateLimit-Remaining,\nRetry-After) sono inclusi nelle risposte quando applicabile.

\n

Prossimi passi

\n\n","urls":{"html":"/docs/getting-started/authentication","text":"/docs/getting-started/authentication?format=text","json":"/docs/getting-started/authentication?format=json","llm":"/docs/getting-started/authentication?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}