{"title":"Authenticatie & Mind Keys","slug":"authentication","category":"getting-started","summary":"Hoe Synapse-authenticatie werkt: Mind Keys voor agents, JWT's voor mensen, ?key= voor URL-only tools.","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":443,"read_minutes":2,"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":"nl","translated":true,"requested_lang":"nl","content_markdown":"\n# Authenticatie & Mind Keys\n\nSynapse gebruikt twee authenticatiemethoden, elk geoptimaliseerd voor een ander doel.\nHet verschil begrijpen is essentieel voor het bouwen van betrouwbare integraties.\n\n## Twee auth-methoden\n\n| Methode | Gebruik | Ratelimit | Verval |\n|---------|---------|-----------|--------|\n| **Mind Key** | LLM-agents, geautomatiseerde tools | Geen (header) / 60 per min (query) | Nooit |\n| **JWT** | Mensgerichte UI, account-operaties | Geen | 7 dagen |\n\n## Mind Key (voor agents)\n\nEen Mind Key is een tenant-scoped API-token. Het authenticeert de data van één mind\n(herinneringen, taken, chat, scripts, enz.). Gebruik het voor:\n\n- LLM-agents die de API aanroepen\n- Achtergrond-automatiseringsscripts\n- MCP-server-configuratie\n- Elke langlevende integratie\n\n### Header-authenticatie (aanbevolen)\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n### Queryparameter (voor URL-only tools)\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> De `?key=`-queryparameter is gelimiteerd tot **60 verzoeken per minuut**.\n> De Bearer-header heeft geen ratelimit. Gebruik de header wanneer uw client\n> aangepaste headers ondersteunt.\n\n### Een Mind Key aanmaken\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\nDe respons bevat `mind_key` — **sla deze onmiddellijk op**, deze wordt slechts één keer getoond.\n\n### Uw minds tonen\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds\n```\n\n### Een mind verwijderen (onomkeerbaar!)\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT (voor mensen)\n\nJWT's authenticeren het **gebruikersaccount**, niet een specifieke mind. Gebruik ze voor:\n\n- Accountregistratie en login\n- Minds aanmaken/tonen/verwijderen\n- Minds delen met andere gebruikers\n- Web Push-abonnementsbeheer\n\n### Registreren\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\nRetourneert: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Inloggen\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\nRetourneert: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### JWT-verval\n\nJWT's vervallen na **7 dagen**. Wanneer een JWT vervalt, roept u gewoon opnieuw `/login`\naan om een verse te krijgen. De Mind Key vervalt nooit, dus bestaande agent-integraties\nblijven werken.\n\n## Beveiligings-best-practices\n\n> [!CRITICAL]\n> - **Commit Mind Keys nooit naar git.** Gebruik omgevingsvariabelen.\n> - **Log Mind Keys nooit.** Maskeer ze in logs (`mk_***...***xyz`).\n> - **Roteer sleutels** bij vermoeden van een lek (verwijder de mind, maak een nieuwe aan).\n> - **Gebruik één mind per project** om de schade bij een lek te beperken.\n\n### Omgevingsvariabele-patroon\n\n```bash\n# .env (NOOIT dit bestand committen)\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### MCP-server-config\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## Multi-mind-patroon\n\nElke gebruiker kan meerdere minds hebben. Veelvoorkomende patronen:\n\n| Mind-naam | Doel |\n|-----------|------|\n| `work` | Werkgerelateerde herinneringen |\n| `personal` | Persoonlijke voorkeuren, familie |\n| `project-synapse` | Specifieke projectcontext |\n| `learning-german` | Leervoortgang |\n| `assistant-default` | Algemene fallback |\n\nGebruik verschillende Mind Keys voor verschillende LLM-sessies om contexten gescheiden te houden.\n\n## Ratelimits\n\n| Auth-methode | Limiet | Bereik |\n|--------------|--------|--------|\n| Mind Key (header) | Geen | Per-mind |\n| Mind Key (?key=) | 60/min | Per-IP |\n| JWT (header) | Geen | Per-gebruiker |\n| Openbare eindpunten | Geen | Globaal |\n\nRatelimit-headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`)\nworden in responsen opgenomen waar van toepassing.\n\n## Volgende stappen\n\n- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — wanneer welke gebruiken\n- [Memory API](/docs/api/memory) — wat u kunt doen met een Mind Key\n- [User API](/docs/api/user) — accountbeheer met JWT's\n","content_html":"

Authenticatie & Mind Keys

\n

Synapse gebruikt twee authenticatiemethoden, elk geoptimaliseerd voor een ander doel.\nHet verschil begrijpen is essentieel voor het bouwen van betrouwbare integraties.

\n

Twee auth-methoden

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
MethodeGebruikRatelimitVerval
Mind KeyLLM-agents, geautomatiseerde toolsGeen (header) / 60 per min (query)Nooit
JWTMensgerichte UI, account-operatiesGeen7 dagen
\n

Mind Key (voor agents)

\n

Een Mind Key is een tenant-scoped API-token. Het authenticeert de data van één mind\n(herinneringen, taken, chat, scripts, enz.). Gebruik het voor:

\n\n

Header-authenticatie (aanbevolen)

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

Queryparameter (voor URL-only tools)

\n
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
De `?key=`-queryparameter is gelimiteerd tot **60 verzoeken per minuut**.\nDe Bearer-header heeft geen ratelimit. Gebruik de header wanneer uw client\naangepaste headers ondersteunt.

Een Mind Key aanmaken

\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"}'

De respons bevat mind_key — sla deze onmiddellijk op, deze wordt slechts één keer getoond.

\n

Uw minds tonen

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

Een mind verwijderen (onomkeerbaar!)

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

JWT (voor mensen)

\n

JWT's authenticeren het gebruikersaccount, niet een specifieke mind. Gebruik ze voor:

\n\n

Registreren

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

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

\n

Inloggen

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

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

\n

JWT-verval

\n

JWT's vervallen na 7 dagen. Wanneer een JWT vervalt, roept u gewoon opnieuw /login\naan om een verse te krijgen. De Mind Key vervalt nooit, dus bestaande agent-integraties\nblijven werken.

\n

Beveiligings-best-practices

\n

Omgevingsvariabele-patroon

\n
# .env (NOOIT dit bestand committen)\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});

MCP-server-config

\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}

Multi-mind-patroon

\n

Elke gebruiker kan meerdere minds hebben. Veelvoorkomende patronen:

\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
Mind-naamDoel
workWerkgerelateerde herinneringen
personalPersoonlijke voorkeuren, familie
project-synapseSpecifieke projectcontext
learning-germanLeervoortgang
assistant-defaultAlgemene fallback
\n

Gebruik verschillende Mind Keys voor verschillende LLM-sessies om contexten gescheiden te houden.

\n

Ratelimits

\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
Auth-methodeLimietBereik
Mind Key (header)GeenPer-mind
Mind Key (?key=)60/minPer-IP
JWT (header)GeenPer-gebruiker
Openbare eindpuntenGeenGlobaal
\n

Ratelimit-headers (X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After)\nworden in responsen opgenomen waar van toepassing.

\n

Volgende stappen

\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"]}