# 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

| Vous voulez... | Utiliser |
|----------------|-----|
| Stocker / rappeler des mémoires | Mind Key |
| Envoyer / poller des messages chat | Mind Key |
| Gérer des tâches | Mind Key |
| Stocker des scripts | Mind Key |
| Enregistrer des webhooks | Mind Key |
| Contrôler des ordinateurs | Mind Key (côté utilisateur) / Computer Token (côté agent) |
| Inscrire un compte utilisateur | Aucune (public) |
| Se connecter | Aucune (public) |
| Créer / lister / supprimer des minds | JWT |
| Partager un mind avec un autre utilisateur | JWT |
| S'abonner aux notifications web push | JWT |
| Consulter le journal d'audit | Mind Key |

## La règle simple

> [!TIP]
> **Si ça touche les données d'un seul mind → Mind Key.**
> **Si ça gère le compte ou les métadonnées de mind → JWT.**

## 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é.

| Endpoint | Auth |
|----------|------|
| `GET /computers/me/poll` | Computer Token |
| `POST /computers/me/commands/:cid/result` | Computer Token |
| `GET /computers/list` | Mind Key ou JWT |
| `POST /computers/:id/commands` | Mind Key ou JWT |

## 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

| Jeton | Format | Exemple |
|-------|--------|---------|
| Mind Key | `mk_` + 36 caractères | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |
| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| Computer Token | `ct_` + 36 caractères | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |

## Prochaines étapes

- [Authentification](/docs/getting-started/authentication) — guide complet d'auth
- [API Utilisateur & Minds](/docs/api/user) — endpoints protégés par JWT
- [API Memory](/docs/api/memory) — endpoints protégés par Mind Key