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

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)

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

Parametro query (per strumenti solo-URL)

curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere

Creare una Mind Key

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

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

Elencare le sue menti

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

Eliminare una mente (irreversibile!)

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

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

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

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

Login

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

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

Scadenza del JWT

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

Best practice di sicurezza

Modello con variabili di ambiente

# .env (NEVER commit this file)
SYNAPSE_MIND_KEY=mk_yourMindKeyHere
SYNAPSE_URL=https://synapse.schaefer.zone

// Node.js
const mindKey = process.env.SYNAPSE_MIND_KEY;
const url = process.env.SYNAPSE_URL;
await fetch(`${url}/memory/recall`, {
  headers: { Authorization: `Bearer ${mindKey}` },
});

Configurazione del server MCP

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

Modello multi-mente

Ogni utente può avere menti multiple. Modelli comuni:

Usi Mind Key diverse per sessioni LLM diverse per mantenere i contesti isolati.

Limiti di traffico

Gli header di rate limit (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After) 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