{"title":"Аутентификация и Mind Key","slug":"authentication","category":"getting-started","summary":"Как работает аутентификация в Synapse: Mind Key для агентов, JWT для людей, ?key= для инструментов, работающих только с URL.","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":460,"read_minutes":2,"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":"ru","translated":true,"requested_lang":"ru","content_markdown":"\n# Аутентификация и Mind Key\n\nSynapse использует два способа аутентификации, каждый оптимизирован под свой\nсценарий. Понимание различий необходимо для создания надёжных интеграций.\n\n## Два способа аутентификации\n\n| Способ | Сценарий | Лимит запросов | Срок действия |\n|--------|----------|------------|--------|\n| **Mind Key** | LLM-агенты, автоматизированные инструменты | Нет (заголовок) / 60/мин (query) | Бессрочно |\n| **JWT** | Человеко-ориентированный UI, операции с аккаунтом | Нет | 7 дней |\n\n## Mind Key (для агентов)\n\nMind Key — это токен API с областью действия на арендатора. Он аутентифицирует\nданные одного mind (воспоминания, задачи, чат, скрипты и т. д.). Используйте его для:\n\n- LLM-агентов, вызывающих API\n- Фоновых скриптов автоматизации\n- Конфигурации MCP-сервера\n- Любой долгоживущей интеграции\n\n### Аутентификация через заголовок (рекомендуется)\n\n```bash\ncurl -H \"Authorization: Bearer mk_yourMindKeyHere\" \\\n     https://synapse.schaefer.zone/memory/recall\n```\n\n### Через query-параметр (для инструментов, работающих только с URL)\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> Query-параметр `?key=` ограничен **60 запросами в минуту**.\n> Заголовок Bearer не имеет лимита. Используйте заголовок всегда, когда клиент\n> поддерживает пользовательские заголовки.\n\n### Создание 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\nОтвет включает `mind_key` — **сохраните его немедленно**, он показывается только один раз.\n\n### Получение списка своих mind\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_JWT\" \\\n     https://synapse.schaefer.zone/minds\n```\n\n### Удаление mind (необратимо!)\n\n```bash\ncurl -X DELETE -H \"Authorization: Bearer YOUR_JWT\" \\\n     https://synapse.schaefer.zone/minds/m_xyz789\n```\n\n## JWT (для людей)\n\nJWT аутентифицирует **аккаунт пользователя**, а не конкретный mind. Используйте их для:\n\n- Регистрации и входа в аккаунт\n- Создания / получения списка / удаления mind\n- Передачи mind другим пользователям\n- Управления подписками Web Push\n\n### Регистрация\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\nВозвращает: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Вход\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\nВозвращает: `{ \"jwt\": \"eyJ...\", \"user\": {...} }`\n\n### Срок действия JWT\n\nJWT истекает через **7 дней**. После истечения просто вызовите `/login` снова,\nчтобы получить новый. Mind Key не истекает, поэтому существующие интеграции\nагентов продолжают работать.\n\n## Лучшие практики безопасности\n\n> [!CRITICAL]\n> - **Никогда не коммитьте Mind Key в git.** Используйте переменные окружения.\n> - **Никогда не логируйте Mind Key.** Маскируйте их в логах (`mk_***...***xyz`).\n> - **Ротируйте ключи** при подозрении на утечку (удалите mind, создайте новый).\n> - **Используйте один mind на проект**, чтобы ограничить масштаб ущерба при утечке ключа.\n\n### Паттерн переменных окружения\n\n```bash\n# .env (NEVER commit this file)\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### Конфигурация 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## Паттерн нескольких mind\n\nУ каждого пользователя может быть несколько mind. Типовые паттерны:\n\n| Имя mind | Назначение |\n|-----------|---------|\n| `work` | Рабочие воспоминания |\n| `personal` | Личные предпочтения, семья |\n| `project-synapse` | Контекст конкретного проекта |\n| `learning-german` | Прогресс обучения |\n| `assistant-default` | Универсальный fallback |\n\nИспользуйте разные Mind Key в разных LLM-сессиях, чтобы контексты были изолированы.\n\n## Лимиты запросов\n\n| Способ аутентификации | Лимит | Область |\n|-------------|-------|-------|\n| Mind Key (заголовок) | Нет | На mind |\n| Mind Key (?key=) | 60/мин | На IP |\n| JWT (заголовок) | Нет | На пользователя |\n| Публичные эндпоинты | Нет | Глобально |\n\nЗаголовки лимитов (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`)\nвключаются в ответы при применимости.\n\n## Следующие шаги\n\n- [Mind Key против JWT](/docs/getting-started/mind-key-vs-jwt) — когда что использовать\n- [Memory API](/docs/api/memory) — что можно делать с Mind Key\n- [User API](/docs/api/user) — управление аккаунтом с JWT\n","content_html":"<h1>Аутентификация и Mind Key</h1>\n<p>Synapse использует два способа аутентификации, каждый оптимизирован под свой\nсценарий. Понимание различий необходимо для создания надёжных интеграций.</p>\n<h2>Два способа аутентификации</h2>\n<table>\n<thead>\n<tr>\n<th>Способ</th>\n<th>Сценарий</th>\n<th>Лимит запросов</th>\n<th>Срок действия</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><strong>Mind Key</strong></td>\n<td>LLM-агенты, автоматизированные инструменты</td>\n<td>Нет (заголовок) / 60/мин (query)</td>\n<td>Бессрочно</td>\n</tr>\n<tr>\n<td><strong>JWT</strong></td>\n<td>Человеко-ориентированный UI, операции с аккаунтом</td>\n<td>Нет</td>\n<td>7 дней</td>\n</tr>\n</tbody></table>\n<h2>Mind Key (для агентов)</h2>\n<p>Mind Key — это токен API с областью действия на арендатора. Он аутентифицирует\nданные одного mind (воспоминания, задачи, чат, скрипты и т. д.). Используйте его для:</p>\n<ul>\n<li>LLM-агентов, вызывающих API</li>\n<li>Фоновых скриптов автоматизации</li>\n<li>Конфигурации MCP-сервера</li>\n<li>Любой долгоживущей интеграции</li>\n</ul>\n<h3>Аутентификация через заголовок (рекомендуется)</h3>\n<pre><code class=\"hljs language-bash\">curl -H <span class=\"hljs-string\">&quot;Authorization: Bearer mk_yourMindKeyHere&quot;</span> \\\n     https://synapse.schaefer.zone/memory/recall</code></pre><h3>Через query-параметр (для инструментов, работающих только с URL)</h3>\n<pre><code class=\"hljs language-bash\">curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere</code></pre><div class=\"callout callout-warn\">Query-параметр `?key=` ограничен **60 запросами в минуту**.\nЗаголовок Bearer не имеет лимита. Используйте заголовок всегда, когда клиент\nподдерживает пользовательские заголовки.</div><h3>Создание Mind Key</h3>\n<pre><code class=\"hljs language-bash\">curl -X POST https://synapse.schaefer.zone/minds \\\n  -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_JWT&quot;</span> \\\n  -H <span class=\"hljs-string\">&quot;Content-Type: application/json&quot;</span> \\\n  -d <span class=\"hljs-string\">&#x27;{&quot;name&quot;: &quot;Work Mind&quot;, &quot;description&quot;: &quot;Project memories&quot;}&#x27;</span></code></pre><p>Ответ включает <code>mind_key</code> — <strong>сохраните его немедленно</strong>, он показывается только один раз.</p>\n<h3>Получение списка своих mind</h3>\n<pre><code class=\"hljs language-bash\">curl -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_JWT&quot;</span> \\\n     https://synapse.schaefer.zone/minds</code></pre><h3>Удаление mind (необратимо!)</h3>\n<pre><code class=\"hljs language-bash\">curl -X DELETE -H <span class=\"hljs-string\">&quot;Authorization: Bearer YOUR_JWT&quot;</span> \\\n     https://synapse.schaefer.zone/minds/m_xyz789</code></pre><h2>JWT (для людей)</h2>\n<p>JWT аутентифицирует <strong>аккаунт пользователя</strong>, а не конкретный mind. Используйте их для:</p>\n<ul>\n<li>Регистрации и входа в аккаунт</li>\n<li>Создания / получения списка / удаления mind</li>\n<li>Передачи mind другим пользователям</li>\n<li>Управления подписками Web Push</li>\n</ul>\n<h3>Регистрация</h3>\n<pre><code class=\"hljs language-bash\">curl -X POST https://synapse.schaefer.zone/register \\\n  -H <span class=\"hljs-string\">&quot;Content-Type: application/json&quot;</span> \\\n  -d <span class=\"hljs-string\">&#x27;{&quot;email&quot;: &quot;you@example.com&quot;, &quot;password&quot;: &quot;secret&quot;}&#x27;</span></code></pre><p>Возвращает: <code>{ &quot;jwt&quot;: &quot;eyJ...&quot;, &quot;user&quot;: {...} }</code></p>\n<h3>Вход</h3>\n<pre><code class=\"hljs language-bash\">curl -X POST https://synapse.schaefer.zone/login \\\n  -H <span class=\"hljs-string\">&quot;Content-Type: application/json&quot;</span> \\\n  -d <span class=\"hljs-string\">&#x27;{&quot;email&quot;: &quot;you@example.com&quot;, &quot;password&quot;: &quot;secret&quot;}&#x27;</span></code></pre><p>Возвращает: <code>{ &quot;jwt&quot;: &quot;eyJ...&quot;, &quot;user&quot;: {...} }</code></p>\n<h3>Срок действия JWT</h3>\n<p>JWT истекает через <strong>7 дней</strong>. После истечения просто вызовите <code>/login</code> снова,\nчтобы получить новый. Mind Key не истекает, поэтому существующие интеграции\nагентов продолжают работать.</p>\n<h2>Лучшие практики безопасности</h2>\n<div class=\"callout callout-critical\"></div><h3>Паттерн переменных окружения</h3>\n<pre><code class=\"hljs language-bash\"><span class=\"hljs-comment\"># .env (NEVER commit this file)</span>\nSYNAPSE_MIND_KEY=mk_yourMindKeyHere\nSYNAPSE_URL=https://synapse.schaefer.zone</code></pre><pre><code class=\"hljs language-typescript\"><span class=\"hljs-comment\">// Node.js</span>\n<span class=\"hljs-keyword\">const</span> mindKey = process.<span class=\"hljs-property\">env</span>.<span class=\"hljs-property\">SYNAPSE_MIND_KEY</span>;\n<span class=\"hljs-keyword\">const</span> url = process.<span class=\"hljs-property\">env</span>.<span class=\"hljs-property\">SYNAPSE_URL</span>;\n<span class=\"hljs-keyword\">await</span> <span class=\"hljs-title function_\">fetch</span>(<span class=\"hljs-string\">`<span class=\"hljs-subst\">${url}</span>/memory/recall`</span>, {\n  <span class=\"hljs-attr\">headers</span>: { <span class=\"hljs-title class_\">Authorization</span>: <span class=\"hljs-string\">`Bearer <span class=\"hljs-subst\">${mindKey}</span>`</span> },\n});</code></pre><h3>Конфигурация MCP-сервера</h3>\n<pre><code class=\"hljs language-json\"><span class=\"hljs-punctuation\">{</span>\n  <span class=\"hljs-attr\">&quot;mcpServers&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-punctuation\">{</span>\n    <span class=\"hljs-attr\">&quot;synapse&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-punctuation\">{</span>\n      <span class=\"hljs-attr\">&quot;command&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;npx&quot;</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;args&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-punctuation\">[</span><span class=\"hljs-string\">&quot;-y&quot;</span><span class=\"hljs-punctuation\">,</span> <span class=\"hljs-string\">&quot;synapse-mcp-api@latest&quot;</span><span class=\"hljs-punctuation\">]</span><span class=\"hljs-punctuation\">,</span>\n      <span class=\"hljs-attr\">&quot;env&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-punctuation\">{</span>\n        <span class=\"hljs-attr\">&quot;SYNAPSE_MIND_KEY&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;mk_yourMindKeyHere&quot;</span><span class=\"hljs-punctuation\">,</span>\n        <span class=\"hljs-attr\">&quot;SYNAPSE_URL&quot;</span><span class=\"hljs-punctuation\">:</span> <span class=\"hljs-string\">&quot;https://synapse.schaefer.zone&quot;</span>\n      <span class=\"hljs-punctuation\">}</span>\n    <span class=\"hljs-punctuation\">}</span>\n  <span class=\"hljs-punctuation\">}</span>\n<span class=\"hljs-punctuation\">}</span></code></pre><h2>Паттерн нескольких mind</h2>\n<p>У каждого пользователя может быть несколько mind. Типовые паттерны:</p>\n<table>\n<thead>\n<tr>\n<th>Имя mind</th>\n<th>Назначение</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>work</code></td>\n<td>Рабочие воспоминания</td>\n</tr>\n<tr>\n<td><code>personal</code></td>\n<td>Личные предпочтения, семья</td>\n</tr>\n<tr>\n<td><code>project-synapse</code></td>\n<td>Контекст конкретного проекта</td>\n</tr>\n<tr>\n<td><code>learning-german</code></td>\n<td>Прогресс обучения</td>\n</tr>\n<tr>\n<td><code>assistant-default</code></td>\n<td>Универсальный fallback</td>\n</tr>\n</tbody></table>\n<p>Используйте разные Mind Key в разных LLM-сессиях, чтобы контексты были изолированы.</p>\n<h2>Лимиты запросов</h2>\n<table>\n<thead>\n<tr>\n<th>Способ аутентификации</th>\n<th>Лимит</th>\n<th>Область</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Mind Key (заголовок)</td>\n<td>Нет</td>\n<td>На mind</td>\n</tr>\n<tr>\n<td>Mind Key (?key=)</td>\n<td>60/мин</td>\n<td>На IP</td>\n</tr>\n<tr>\n<td>JWT (заголовок)</td>\n<td>Нет</td>\n<td>На пользователя</td>\n</tr>\n<tr>\n<td>Публичные эндпоинты</td>\n<td>Нет</td>\n<td>Глобально</td>\n</tr>\n</tbody></table>\n<p>Заголовки лимитов (<code>X-RateLimit-Limit</code>, <code>X-RateLimit-Remaining</code>, <code>Retry-After</code>)\nвключаются в ответы при применимости.</p>\n<h2>Следующие шаги</h2>\n<ul>\n<li><a href=\"/docs/getting-started/mind-key-vs-jwt\">Mind Key против JWT</a> — когда что использовать</li>\n<li><a href=\"/docs/api/memory\">Memory API</a> — что можно делать с Mind Key</li>\n<li><a href=\"/docs/api/user\">User API</a> — управление аккаунтом с JWT</li>\n</ul>\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"]}