{"title":"Authentification & Mind Keys","slug":"authentication","category":"getting-started","summary":"Comment fonctionne l'authentification Synapse : Mind Keys pour les agents, JWT pour les humains, ?key= pour les outils n'utilisant que des URLs.","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":549,"read_minutes":3,"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":"fr","translated":true,"requested_lang":"fr","content_markdown":"\n# Authentification & Mind Keys\n\nSynapse utilise deux méthodes d'authentification, chacune optimisée pour un cas\nd'usage différent. Comprendre la différence est essentiel pour construire des\nintégrations fiables.\n\n## Deux méthodes d'auth\n\n| Méthode | Cas d'usage | Limite de débit | Expiration |\n|--------|----------|------------|--------|\n| **Mind Key** | Agents LLM, outils automatisés | Aucune (en-tête) / 60 min (requête) | Jamais |\n| **JWT** | Interface humaine, opérations de compte | Aucune | 7 jours |\n\n## Mind Key (pour les agents)\n\nUne Mind Key est un jeton d'API limité au tenant. Elle authentifie les données d'un\nseul mind (mémoires, tâches, chat, scripts, etc.). Utilisez-la pour :\n\n- Les agents LLM appelant l'API\n- Les scripts d'automatisation en arrière-plan\n- La configuration du serveur MCP\n- Toute intégration longue durée\n\n### Authentification par en-tête (recommandée)\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n https://synapse.schaefer.zone/memory/recall\n```\n\n### Paramètre de requête (pour les outils n'utilisant que des URLs)\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> Le paramètre de requête `?key=` est limité à **60 requêtes par minute**. L'en-tête\n> Bearer n'a pas de limite de débit. Utilisez l'en-tête chaque fois que votre client\n> prend en charge les en-têtes personnalisés.\n\n### Créer une Mind Key\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\nLa réponse inclut `mind_key` — **sauvegardez-la immédiatement**, elle n'est affichée\nqu'une seule fois.\n\n### Lister vos minds\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds\n```\n\n### Supprimer un mind (irréversible !)\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT (pour les humains)\n\nLes JWT authentifient le **compte utilisateur**, pas un mind spécifique. Utilisez-les\npour :\n\n- L'inscription et la connexion au compte\n- La création / liste / suppression de minds\n- Le partage de minds avec d'autres utilisateurs\n- La gestion des abonnements Web Push\n\n### Inscription\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\nRenvoie : `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Connexion\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\nRenvoie : `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Expiration du JWT\n\nLes JWT expirent après **7 jours**. Une fois expirés, appelez simplement `/login` à\nnouveau pour en obtenir un nouveau. La Mind Key n'expire jamais, donc les intégrations\nd'agents existantes continuent de fonctionner.\n\n## Bonnes pratiques de sécurité\n\n> [!CRITICAL]\n> - **Ne commitez jamais de Mind Keys dans git.** Utilisez des variables d'environnement.\n> - **Ne journalisez jamais de Mind Keys.** Masquez-les dans les logs (`mk_***...***xyz`).\n> - **Pivotez les clés** si vous suspectez une fuite (supprimez le mind, créez-en un nouveau).\n> - **Utilisez un mind par projet** pour limiter le rayon d'impact en cas de fuite de clé.\n\n### Schéma de variable d'environnement\n\n```bash\n# .env (NE JAMAIS commiter ce fichier)\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### Configuration du serveur MCP\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## Schéma multi-mind\n\nChaque utilisateur peut avoir plusieurs minds. Schémas courants :\n\n| Nom du mind | Rôle |\n|-----------|---------|\n| `work` | Mémoires liées au travail |\n| `personal` | Préférences personnelles, famille |\n| `project-synapse` | Contexte de projet spécifique |\n| `learning-german` | Progression d'apprentissage |\n| `assistant-default` | Fallback à usage général |\n\nUtilisez différentes Mind Keys pour différentes sessions LLM afin de garder les\ncontextes isolés.\n\n## Limites de débit\n\n| Méthode d'auth | Limite | Portée |\n|-------------|-------|-------|\n| Mind Key (en-tête) | Aucune | Par mind |\n| Mind Key (?key=) | 60/min | Par IP |\n| JWT (en-tête) | Aucune | Par utilisateur |\n| Endpoints publics | Aucune | Globale |\n\nLes en-têtes de limite de débit (`X-RateLimit-Limit`, `X-RateLimit-Remaining`,\n`Retry-After`) sont inclus dans les réponses le cas échéant.\n\n## Prochaines étapes\n\n- [Mind Key vs JWT](/docs/getting-started/mind-key-vs-jwt) — quand utiliser laquelle\n- [API Memory](/docs/api/memory) — ce que vous pouvez faire avec une Mind Key\n- [API User](/docs/api/user) — gestion de compte avec JWT\n","content_html":"

Authentification & Mind Keys

\n

Synapse utilise deux méthodes d'authentification, chacune optimisée pour un cas\nd'usage différent. Comprendre la différence est essentiel pour construire des\nintégrations fiables.

\n

Deux méthodes d'auth

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
MéthodeCas d'usageLimite de débitExpiration
Mind KeyAgents LLM, outils automatisésAucune (en-tête) / 60 min (requête)Jamais
JWTInterface humaine, opérations de compteAucune7 jours
\n

Mind Key (pour les agents)

\n

Une Mind Key est un jeton d'API limité au tenant. Elle authentifie les données d'un\nseul mind (mémoires, tâches, chat, scripts, etc.). Utilisez-la pour :

\n\n

Authentification par en-tête (recommandée)

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

Paramètre de requête (pour les outils n'utilisant que des URLs)

\n
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
Le paramètre de requête `?key=` est limité à **60 requêtes par minute**. L'en-tête\nBearer n'a pas de limite de débit. Utilisez l'en-tête chaque fois que votre client\nprend en charge les en-têtes personnalisés.

Créer une Mind Key

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

La réponse inclut mind_key — sauvegardez-la immédiatement, elle n'est affichée\nqu'une seule fois.

\n

Lister vos minds

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

Supprimer un mind (irréversible !)

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

JWT (pour les humains)

\n

Les JWT authentifient le compte utilisateur, pas un mind spécifique. Utilisez-les\npour :

\n\n

Inscription

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

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

\n

Connexion

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

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

\n

Expiration du JWT

\n

Les JWT expirent après 7 jours. Une fois expirés, appelez simplement /login à\nnouveau pour en obtenir un nouveau. La Mind Key n'expire jamais, donc les intégrations\nd'agents existantes continuent de fonctionner.

\n

Bonnes pratiques de sécurité

\n

Schéma de variable d'environnement

\n
# .env (NE JAMAIS commiter ce fichier)\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});

Configuration du serveur MCP

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

Schéma multi-mind

\n

Chaque utilisateur peut avoir plusieurs minds. Schémas courants :

\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
Nom du mindRôle
workMémoires liées au travail
personalPréférences personnelles, famille
project-synapseContexte de projet spécifique
learning-germanProgression d'apprentissage
assistant-defaultFallback à usage général
\n

Utilisez différentes Mind Keys pour différentes sessions LLM afin de garder les\ncontextes isolés.

\n

Limites de débit

\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
Méthode d'authLimitePortée
Mind Key (en-tête)AucunePar mind
Mind Key (?key=)60/minPar IP
JWT (en-tête)AucunePar utilisateur
Endpoints publicsAucuneGlobale
\n

Les en-têtes de limite de débit (X-RateLimit-Limit, X-RateLimit-Remaining,\nRetry-After) sont inclus dans les réponses le cas échéant.

\n

Prochaines étapes

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