Mind Key vs JWT — Wanneer welke?

Synapse heeft twee authenticatie-tokens. De verkeerde kiezen leidt tot 401-fouten. Deze handleiding geeft u een helder beslissingskader.

Snelle beslissingstabel

De eenvoudige regel

Mind Key — Data-toegangstoken

Een Mind Key verleent toegang tot de data van één mind. Het is een langlevend token dat nooit vervalt (tot de mind wordt verwijderd). Perfect voor:

• LLM-agents die herinneringen tussen sessies persistent maken
• Achtergrond-cron-jobs
• MCP-server-configuratie
• Webhook-integraties
• Mobiele apps die memory lezen

Wat Mind Key kan doen

• GET /memory/recall — alle herinneringen in deze mind lezen
• POST /memory — herinneringen opslaan/bijwerken
• GET /chat/poll — chatberichten lezen
• POST /chat/reply — chatberichten sturen
• GET /mind/tasks — taken tonen
• POST /mind/task — taken aanmaken
• POST /script — scripts opslaan
• POST /webhooks — webhooks registreren
• POST /computers/:id/commands — computer-commando's in de wachtrij plaatsen

Wat Mind Key NIET kan doen

• Minds aanmaken/tonen/verwijderen (JWT nodig)
• Mind delen met andere gebruiker (JWT nodig)
• Gebruikersaccount-info bekijken (JWT nodig)
• Abonneren op web push (JWT nodig)

JWT — Accountbeheer-token

Een JWT authenticeert het gebruikersaccount. Het vervalt na 7 dagen en wordt gebruikt voor accountniveau-operaties die meerdere minds beslaan of andere gebruikers betreffen.

Wat JWT kan doen

• POST /minds — een nieuwe mind aanmaken (retourneert een nieuwe Mind Key)
• GET /minds — alle minds voor deze gebruiker tonen
• DELETE /minds/:id — een mind verwijderen
• POST /sharing — een mind delen met een andere gebruiker
• POST /push/subscribe — abonneren op web push-meldingen
• GET /sharing — mind-shares tonen

Wat JWT NIET kan doen

• Herinneringen lezen/schrijven (Mind Key nodig)
• Chatberichten sturen (Mind Key nodig)
• Taken beheren (Mind Key nodig)
• Webhooks registreren (Mind Key nodig)

Speciaal geval: Computer Token

De /computers/me/*-eindpunten (agent-gericht, voor de screen-remote-agent) gebruiken een derde tokentype: de Computer Token. Dit token wordt geretourneerd door POST /computers/register bij het inwisselen van een installatiecode, en is specifiek voor één geregistreerde computer.

Veelvoorkomende patronen

Patroon 1: Enkele LLM-agent

1. Eenmalig registreren → JWT krijgen
2. Eén mind aanmaken → Mind Key krijgen
3. LLM gebruikt Mind Key voor alles

Patroon 2: Multi-project-agent

1. Eenmalig registreren → JWT krijgen
2. Meerdere minds aanmaken (work, personal, project-x) → meerdere Mind Keys krijgen
3. LLM laadt verschillende Mind Key op basis van context

Patroon 3: Team-deling

1. Gebruiker A maakt een mind aan → krijgt Mind Key A
2. Gebruiker A deelt met Gebruiker B via JWT (POST /sharing)
3. Gebruiker B kan nu benaderen via eigen JWT
4. Voor LLM-toegang moet Gebruiker B een eigen Mind Key aanmaken (of die van A gebruiken)

Patroon 4: MCP-server

MCP-servers gebruiken altijd Mind Key (ingesteld via SYNAPSE_MIND_KEY-env-var). Eén MCP- serverinstantie = één mind. Voor multi-mind-toegang, draai meerdere MCP-instanties of implementeer client-side mind-wisseling.

Token-formaat overzicht

Volgende stappen

• Authenticatie — volledige auth-handleiding
• User & Minds API — JWT-beveiligde eindpunten
• Memory API — Mind Key-beveiligde eindpunten