# Authentification & Mind Keys
SUMMARY: Comment fonctionne l'authentification Synapse : Mind Keys pour les agents, JWT pour les humains, ?key= désactivé par défaut (Bearer uniquement, AUTH_QUERY_KEY_MODE=deny).

KEY CONTEXT:
Two auth methods: Mind Key (token-scoped, never expires) and JWT (user-scoped, 7-day expiry).
Mind Key: Authorization: Bearer mk_xxx (?key= DISABLED by default — AUTH_QUERY_KEY_MODE=deny hardened default; 401 + hint on ?key=)
JWT: Authorization: Bearer eyJ... (120 req/min external IPs, unlimited internal; used for /register, /login, /minds, /sharing)
Mind Key is shown only once at creation. Store it permanently.
Each mind has exactly one Mind Key. Multiple minds = multiple keys.

Authentification & Mind Keys
Synapse utilise deux méthodes d'authentification, chacune optimisée pour un cas
d'usage différent. Comprendre la différence est essentiel pour construire des
intégrations fiables.
Deux méthodes d'auth
| Méthode | Cas d'usage | Limite de débit | Expiration |
|--------|----------|------------|--------|
| Mind Key | Agents LLM, outils automatisés | 120/min (Bearer externe) ; ?key= désactivé par défaut (deny) | Jamais |
| JWT | Interface humaine, opérations de compte | 120/min (IPs externes) | 7 jours |
Mind Key (pour les agents)
Une Mind Key est un jeton d'API limité au tenant. Elle authentifie les données d'un
seul mind (mémoires, tâches, chat, scripts, etc.). Utilisez-la pour :
- Les agents LLM appelant l'API
- Les scripts d'automatisation en arrière-plan
- La configuration du serveur MCP
- Toute intégration longue durée
Authentification par en-tête (recommandée)
[CODE BLOCK]
Paramètre de requête (désactivé par défaut)
[CODE BLOCK]
> [!WARNING]
> Le paramètre de requête  est désactivé par la valeur par défaut durcie
>  : le serveur répond à  avec 401 et l'indication "Query-param auth (?key=) is disabled".
> Bearer uniquement est la valeur par défaut sûre (SSOT : ). Ce n'est que si un
> opérateur définit explicitement  que  fonctionne comme soupape
> de transition avec 60 req/min (par IP). Les clients Bearer externes obtiennent 120 req/min par
> identité ; les réseaux internes fiables ne sont pas limités.
Créer une Mind Key
[CODE BLOCK]
La réponse inclut  — sauvegardez-la immédiatement, elle n'est affichée
qu'une seule fois.
Lister vos minds
[CODE BLOCK]
Supprimer un mind (irréversible !)
[CODE BLOCK]
JWT (pour les humains)
Les JWT authentifient le compte utilisateur, pas un mind spécifique. Utilisez-les
pour :
- L'inscription et la connexion au compte
- La création / liste / suppression de minds
- Le partage de minds avec d'autres utilisateurs
- La gestion des abonnements Web Push
Inscription
[CODE BLOCK]
Renvoie : 
Connexion
[CODE BLOCK]
Renvoie : 
Expiration du JWT
Les JWT expirent après 7 jours. Une fois expirés, appelez simplement  à
nouveau pour en obtenir un nouveau. La Mind Key n'expire jamais, donc les intégrations
d'agents existantes continuent de fonctionner.
Bonnes pratiques de sécurité
> [!CRITICAL]
> - Ne commitez jamais de Mind Keys dans git. Utilisez des variables d'environnement.
> - Ne journalisez jamais de Mind Keys. Masquez-les dans les logs ().
> - Pivotez les clés si vous suspectez une fuite (supprimez le mind, créez-en un nouveau).
> - Utilisez un mind par projet pour limiter le rayon d'impact en cas de fuite de clé.
Schéma de variable d'environnement
[CODE BLOCK]
[CODE BLOCK]
Configuration du serveur MCP
[CODE BLOCK]
Schéma multi-mind
Chaque utilisateur peut avoir plusieurs minds. Schémas courants :
| Nom du mind | Rôle |
|-----------|---------|
|  | Mémoires liées au travail |
|  | Préférences personnelles, famille |
|  | Contexte de projet spécifique |
|  | Progression d'apprentissage |
|  | Fallback à usage général |
Utilisez différentes Mind Keys pour différentes sessions LLM afin de garder les
contextes isolés.
Limites de débit
| Méthode d'auth | Limite | Portée |
|-------------|-------|-------|
| Mind Key (en-tête) | 120/min depuis les IPs externes (par identité) ; illimité pour les réseaux internes de confiance | Par mind |
| Mind Key (?key=, allow uniquement) | 60/min | Par IP |
| JWT (en-tête) | 120 req/min (IPs externes ; illimité pour les réseaux internes de confiance) | Par utilisateur |
| Endpoints publics | Aucune | Globale |
Les en-têtes de limite de débit (, ,
) sont inclus dans les réponses le cas échéant.
Prochaines étapes
- Mind Key vs JWT — quand utiliser laquelle
- API Memory — ce que vous pouvez faire avec une Mind Key
- API User — gestion de compte avec JWT