{"title":"Автентифікація та Mind Keys","slug":"authentication","category":"getting-started","summary":"Як працює автентифікація Synapse: Mind Keys для агентів, JWT для людей, ?key= для URL-only інструментів.","audience":["human","llm"],"tags":["auth","mind-key","jwt","security"],"difficulty":"beginner","updated":"2026-06-27","word_count":463,"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":"uk","translated":true,"requested_lang":"uk","content_markdown":"\n# Автентифікація та Mind Keys\n\nSynapse використовує два методи автентифікації, кожен оптимізований під свій\nваріант використання. Розуміння різниці є необхідним для побудови надійних\nінтеграцій.\n\n## Два методи автентифікації\n\n| Метод | Варіант використання | Обмеження частоти | Термін дії |\n|--------|----------|------------|--------|\n| **Mind Key** | LLM-агенти, інструменти автоматизації | Немає (заголовок) / 60 хв (запит) | Ніколи |\n| **JWT** | Людський інтерфейс, операції облікового запису | Немає | 7 днів |\n\n## Mind Key (для агентів)\n\nMind Key — це API-токен, прив'язаний до тенанта. Він автентифікує дані одного\nmind-у (спогади, завдання, чат, скрипти тощо). Використовуйте для:\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### Параметр запиту (для URL-only інструментів)\n\n```bash\ncurl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere\n```\n\n> [!WARNING]\n> Параметр запиту `?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 днів**. Коли JWT закінчується, просто викличте `/login`\nзнову, щоб отримати новий. Mind Key ніколи не закінчується, тому наявні інтеграції\nагентів продовжують працювати.\n\n## Найкращі практики безпеки\n\n> [!CRITICAL]\n> - **Ніколи не комітьте Mind Keys у git.** Використовуйте змінні середовища.\n> - **Ніколи не логуйте Mind Keys.** Маскуйте їх у логах (`mk_***...***xyz`).\n> - **Ротуйте ключі** у разі підозри на витік (видаліть mind, створіть новий).\n> - **Один mind на проєкт**, щоб обмежити масштаб шкоди при витоку ключа.\n\n### Шаблон змінних середовища\n\n```bash\n# .env (НІКОЛИ не комітьте цей файл)\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 Keys для різних сесій 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`,\n`Retry-After`) включаються у відповіді за потреби.\n\n## Наступні кроки\n\n- [Mind Key проти JWT](/docs/getting-started/mind-key-vs-jwt) — коли що використовувати\n- [Memory API](/docs/api/memory) — що можна робити з Mind Key\n- [API користувачів](/docs/api/user) — керування обліковим записом з JWT\n","content_html":"<h1>Автентифікація та Mind Keys</h1>\n<p>Synapse використовує два методи автентифікації, кожен оптимізований під свій\nваріант використання. Розуміння різниці є необхідним для побудови надійних\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 хв (запит)</td>\n<td>Ніколи</td>\n</tr>\n<tr>\n<td><strong>JWT</strong></td>\n<td>Людський інтерфейс, операції облікового запису</td>\n<td>Немає</td>\n<td>7 днів</td>\n</tr>\n</tbody></table>\n<h2>Mind Key (для агентів)</h2>\n<p>Mind Key — це API-токен, прив&#39;язаний до тенанта. Він автентифікує дані одного\nmind-у (спогади, завдання, чат, скрипти тощо). Використовуйте для:</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>Параметр запиту (для URL-only інструментів)</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\">Параметр запиту `?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>. Коли JWT закінчується, просто викличте <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 (НІКОЛИ не комітьте цей файл)</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>Особисті уподобання, сім&#39;я</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 Keys для різних сесій 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>,\n<code>Retry-After</code>) включаються у відповіді за потреби.</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\">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"]}