Mind Key vs JWT — Quand utiliser laquelle ?

Synapse possède deux jetons d'authentification. Choisir le mauvais mène à des erreurs 401. Ce guide vous donne un cadre de décision clair.

Tableau de décision rapide

La règle simple

Mind Key — jeton d'accès aux données

Une Mind Key accorde l'accès aux données d'un seul mind. C'est un jeton longue durée qui n'expire jamais (jusqu'à la suppression du mind). Parfait pour :

• Les agents LLM persistant des mémoires entre sessions
• Les tâches cron en arrière-plan
• La configuration du serveur MCP
• Les intégrations de webhooks
• Les applications mobiles lisant la mémoire

Ce que la Mind Key peut faire

• GET /memory/recall — lire toutes les mémoires de ce mind
• POST /memory — stocker/mettre à jour des mémoires
• GET /chat/poll — lire les messages de chat
• POST /chat/reply — envoyer des messages de chat
• GET /mind/tasks — lister les tâches
• POST /mind/task — créer des tâches
• POST /script — stocker des scripts
• POST /webhooks — enregistrer des webhooks
• POST /computers/:id/commands — mettre en file des commandes

Ce que la Mind Key NE PEUT PAS faire

• Créer / lister / supprimer des minds (besoin d'un JWT)
• Partager un mind avec un autre utilisateur (besoin d'un JWT)
• Voir les infos du compte utilisateur (besoin d'un JWT)
• S'abonner au web push (besoin d'un JWT)

JWT — jeton de gestion de compte

Un JWT authentifie le compte utilisateur. Il expire après 7 jours et est utilisé pour les opérations au niveau du compte qui couvrent plusieurs minds ou impliquent d'autres utilisateurs.

Ce que le JWT peut faire

• POST /minds — créer un nouveau mind (renvoie une nouvelle Mind Key)
• GET /minds — lister tous les minds de cet utilisateur
• DELETE /minds/:id — supprimer un mind
• POST /sharing — partager un mind avec un autre utilisateur
• POST /push/subscribe — s'abonner aux notifications web push
• GET /sharing — lister les partages de mind

Ce que le JWT NE PEUT PAS faire

• Lire / écrire des mémoires (besoin d'une Mind Key)
• Envoyer des messages de chat (besoin d'une Mind Key)
• Gérer des tâches (besoin d'une Mind Key)
• Enregistrer des webhooks (besoin d'une Mind Key)

Cas particulier : Computer Token

Les endpoints /computers/me/* (côté agent, pour le screen-remote-agent) utilisent un troisième type de jeton : le Computer Token. Ce jeton est renvoyé par POST /computers/register lors de l'échange d'un code d'installation, et est spécifique à un ordinateur enregistré.

Schémas courants

Schéma 1 : agent LLM unique

1. S'inscrire une fois → obtenir un JWT
2. Créer un mind → obtenir une Mind Key
3. Le LLM utilise la Mind Key pour tout

Schéma 2 : agent multi-projets

1. S'inscrire une fois → obtenir un JWT
2. Créer plusieurs minds (travail, personnel, projet-x) → obtenir plusieurs Mind Keys
3. Le LLM charge différentes Mind Keys selon le contexte

Schéma 3 : partage en équipe

1. L'utilisateur A crée un mind → obtient la Mind Key A
2. L'utilisateur A partage avec l'utilisateur B via JWT (POST /sharing)
3. L'utilisateur B peut maintenant y accéder via son propre JWT
4. Pour l'accès LLM, l'utilisateur B doit créer sa propre Mind Key (ou utiliser celle de A)

Schéma 4 : serveur MCP

Les serveurs MCP utilisent toujours la Mind Key (définie via la variable d'environnement SYNAPSE_MIND_KEY). Une instance de serveur MCP = un mind. Pour un accès multi-mind, exécutez plusieurs instances MCP ou implémentez une commutation de mind côté client.

Aide-mémoire des formats de jeton

Prochaines étapes

• Authentification — guide complet d'auth
• API Utilisateur & Minds — endpoints protégés par JWT
• API Memory — endpoints protégés par Mind Key