{"title":"Mind Key против JWT — что когда?","slug":"mind-key-vs-jwt","category":"getting-started","summary":"Руководство по выбору: Mind Key для доступа агента к данным, JWT для управления аккаунтом.","audience":["human","llm"],"tags":["auth","mind-key","jwt","decision-guide"],"difficulty":"beginner","updated":"2026-06-27","word_count":657,"read_minutes":3,"llm_context":"Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.\nJWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.\nSimple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.\nException: /computers/me/* uses Computer Token (not Mind Key or JWT).\n","lang":"ru","translated":true,"requested_lang":"ru","content_markdown":"\n# Mind Key против JWT — что когда?\n\nВ Synapse два типа токенов аутентификации. Выбор неверного приводит к ошибкам 401.\nЭто руководство даёт чёткую основу для выбора.\n\n## Краткая таблица решений\n\n| Вы хотите... | Использовать |\n|----------------|-----|\n| Сохранять / отзывать воспоминания | Mind Key |\n| Отправлять / опрашивать сообщения чата | Mind Key |\n| Управлять задачами | Mind Key |\n| Хранить скрипты | Mind Key |\n| Регистрировать вебхуки | Mind Key |\n| Управлять компьютерами | Mind Key (пользователь) / Computer Token (агент) |\n| Зарегистрировать аккаунт | Нет (публичный) |\n| Войти | Нет (публичный) |\n| Создать / получить список / удалить mind | JWT |\n| Поделиться mind с другим пользователем | JWT |\n| Подписаться на web push-уведомления | JWT |\n| Просмотреть журнал аудита | Mind Key |\n\n## Простое правило\n\n> [!TIP]\n> **Если действие касается данных одного mind → Mind Key.**\n> **Если управляет аккаунтом или метаданными mind → JWT.**\n\n## Mind Key — токен доступа к данным\n\nMind Key даёт доступ к **данным одного mind**. Это долгоживущий токен, который\nне истекает (пока mind не удалён). Идеально для:\n\n- LLM-агентов, сохраняющих память между сессиями\n- Фоновых cron-задач\n- Конфигурации MCP-сервера\n- Интеграций через вебхуки\n- Мобильных приложений, читающих память\n\n### Что может Mind Key\n\n- `GET /memory/recall` — читать все воспоминания этого mind\n- `POST /memory` — сохранять/обновлять воспоминания\n- `GET /chat/poll` — читать сообщения чата\n- `POST /chat/reply` — отправлять сообщения чата\n- `GET /mind/tasks` — получать список задач\n- `POST /mind/task` — создавать задачи\n- `POST /script` — хранить скрипты\n- `POST /webhooks` — регистрировать вебхуки\n- `POST /computers/:id/commands` — ставить команды в очередь\n\n### Что Mind Key НЕ может\n\n- Создавать / получать список / удалять mind (нужен JWT)\n- Делиться mind с другим пользователем (нужен JWT)\n- Просматривать данные аккаунта пользователя (нужен JWT)\n- Подписываться на web push (нужен JWT)\n\n## JWT — токен управления аккаунтом\n\nJWT аутентифицирует **аккаунт пользователя**. Он истекает через 7 дней и\nиспользуется для операций на уровне аккаунта, охватывающих несколько mind или\nдругих пользователей.\n\n### Что может JWT\n\n- `POST /minds` — создать новый mind (возвращает новый Mind Key)\n- `GET /minds` — получить список всех mind пользователя\n- `DELETE /minds/:id` — удалить mind\n- `POST /sharing` — поделиться mind с другим пользователем\n- `POST /push/subscribe` — подписаться на web push-уведомления\n- `GET /sharing` — получить список общих mind\n\n### Что JWT НЕ может\n\n- Читать / писать воспоминания (нужен Mind Key)\n- Отправлять сообщения чата (нужен Mind Key)\n- Управлять задачами (нужен Mind Key)\n- Регистрировать вебхуки (нужен Mind Key)\n\n## Особый случай: Computer Token\n\nЭндпоинты `/computers/me/*` (для агентов, screen-remote-agent) используют\nтретий тип токена: **Computer Token**. Он возвращается `POST /computers/register`\nпри активации установочного кода и привязан к конкретному зарегистрированному\nкомпьютеру.\n\n| Эндпоинт | Аутентификация |\n|----------|------|\n| `GET /computers/me/poll` | Computer Token |\n| `POST /computers/me/commands/:cid/result` | Computer Token |\n| `GET /computers/list` | Mind Key или JWT |\n| `POST /computers/:id/commands` | Mind Key или JWT |\n\n## Типовые паттерны\n\n### Паттерн 1: одиночный LLM-агент\n\n1. Зарегистрируйтесь один раз → получите JWT\n2. Создайте один mind → получите Mind Key\n3. LLM использует Mind Key для всего\n\n### Паттерн 2: агент с несколькими проектами\n\n1. Зарегистрируйтесь один раз → получите JWT\n2. Создайте несколько mind (work, personal, project-x) → получите несколько Mind Key\n3. LLM загружает разные Mind Key в зависимости от контекста\n\n### Паттерн 3: командный обмен\n\n1. Пользователь A создаёт mind → получает Mind Key A\n2. Пользователь A делится с пользователем B через JWT (`POST /sharing`)\n3. Пользователь B теперь может получить доступ через свой JWT\n4. Для доступа LLM пользователю B нужно создать свой Mind Key (или использовать A)\n\n### Паттерн 4: MCP-сервер\n\nMCP-серверы всегда используют Mind Key (через переменную окружения `SYNAPSE_MIND_KEY`).\nОдин экземпляр MCP-сервера = один mind. Для доступа к нескольким mind запустите\nнесколько экземпляров MCP или реализуйте клиентское переключение mind.\n\n## Шпаргалка по форматам токенов\n\n| Токен | Формат | Пример |\n|-------|--------|---------|\n| Mind Key | `mk_` + 36 символов | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |\n| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |\n| Computer Token | `ct_` + 36 символов | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |\n\n## Следующие шаги\n\n- [Аутентификация](/docs/getting-started/authentication) — полное руководство по аутентификации\n- [User & Minds API](/docs/api/user) — эндпоинты под защитой JWT\n- [Memory API](/docs/api/memory) — эндпоинты под защитой Mind Key\n","content_html":"<h1>Mind Key против JWT — что когда?</h1>\n<p>В Synapse два типа токенов аутентификации. Выбор неверного приводит к ошибкам 401.\nЭто руководство даёт чёткую основу для выбора.</p>\n<h2>Краткая таблица решений</h2>\n<table>\n<thead>\n<tr>\n<th>Вы хотите...</th>\n<th>Использовать</th>\n</tr>\n</thead>\n<tbody><tr>\n<td>Сохранять / отзывать воспоминания</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Отправлять / опрашивать сообщения чата</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Управлять задачами</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Хранить скрипты</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Регистрировать вебхуки</td>\n<td>Mind Key</td>\n</tr>\n<tr>\n<td>Управлять компьютерами</td>\n<td>Mind Key (пользователь) / Computer Token (агент)</td>\n</tr>\n<tr>\n<td>Зарегистрировать аккаунт</td>\n<td>Нет (публичный)</td>\n</tr>\n<tr>\n<td>Войти</td>\n<td>Нет (публичный)</td>\n</tr>\n<tr>\n<td>Создать / получить список / удалить mind</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Поделиться mind с другим пользователем</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Подписаться на web push-уведомления</td>\n<td>JWT</td>\n</tr>\n<tr>\n<td>Просмотреть журнал аудита</td>\n<td>Mind Key</td>\n</tr>\n</tbody></table>\n<h2>Простое правило</h2>\n<div class=\"callout callout-ok\">**Если действие касается данных одного mind → Mind Key.**\n**Если управляет аккаунтом или метаданными mind → JWT.**</div><h2>Mind Key — токен доступа к данным</h2>\n<p>Mind Key даёт доступ к <strong>данным одного mind</strong>. Это долгоживущий токен, который\nне истекает (пока mind не удалён). Идеально для:</p>\n<ul>\n<li>LLM-агентов, сохраняющих память между сессиями</li>\n<li>Фоновых cron-задач</li>\n<li>Конфигурации MCP-сервера</li>\n<li>Интеграций через вебхуки</li>\n<li>Мобильных приложений, читающих память</li>\n</ul>\n<h3>Что может Mind Key</h3>\n<ul>\n<li><code>GET /memory/recall</code> — читать все воспоминания этого mind</li>\n<li><code>POST /memory</code> — сохранять/обновлять воспоминания</li>\n<li><code>GET /chat/poll</code> — читать сообщения чата</li>\n<li><code>POST /chat/reply</code> — отправлять сообщения чата</li>\n<li><code>GET /mind/tasks</code> — получать список задач</li>\n<li><code>POST /mind/task</code> — создавать задачи</li>\n<li><code>POST /script</code> — хранить скрипты</li>\n<li><code>POST /webhooks</code> — регистрировать вебхуки</li>\n<li><code>POST /computers/:id/commands</code> — ставить команды в очередь</li>\n</ul>\n<h3>Что Mind Key НЕ может</h3>\n<ul>\n<li>Создавать / получать список / удалять mind (нужен JWT)</li>\n<li>Делиться mind с другим пользователем (нужен JWT)</li>\n<li>Просматривать данные аккаунта пользователя (нужен JWT)</li>\n<li>Подписываться на web push (нужен JWT)</li>\n</ul>\n<h2>JWT — токен управления аккаунтом</h2>\n<p>JWT аутентифицирует <strong>аккаунт пользователя</strong>. Он истекает через 7 дней и\nиспользуется для операций на уровне аккаунта, охватывающих несколько mind или\nдругих пользователей.</p>\n<h3>Что может JWT</h3>\n<ul>\n<li><code>POST /minds</code> — создать новый mind (возвращает новый Mind Key)</li>\n<li><code>GET /minds</code> — получить список всех mind пользователя</li>\n<li><code>DELETE /minds/:id</code> — удалить mind</li>\n<li><code>POST /sharing</code> — поделиться mind с другим пользователем</li>\n<li><code>POST /push/subscribe</code> — подписаться на web push-уведомления</li>\n<li><code>GET /sharing</code> — получить список общих mind</li>\n</ul>\n<h3>Что JWT НЕ может</h3>\n<ul>\n<li>Читать / писать воспоминания (нужен Mind Key)</li>\n<li>Отправлять сообщения чата (нужен Mind Key)</li>\n<li>Управлять задачами (нужен Mind Key)</li>\n<li>Регистрировать вебхуки (нужен Mind Key)</li>\n</ul>\n<h2>Особый случай: Computer Token</h2>\n<p>Эндпоинты <code>/computers/me/*</code> (для агентов, screen-remote-agent) используют\nтретий тип токена: <strong>Computer Token</strong>. Он возвращается <code>POST /computers/register</code>\nпри активации установочного кода и привязан к конкретному зарегистрированному\nкомпьютеру.</p>\n<table>\n<thead>\n<tr>\n<th>Эндпоинт</th>\n<th>Аутентификация</th>\n</tr>\n</thead>\n<tbody><tr>\n<td><code>GET /computers/me/poll</code></td>\n<td>Computer Token</td>\n</tr>\n<tr>\n<td><code>POST /computers/me/commands/:cid/result</code></td>\n<td>Computer Token</td>\n</tr>\n<tr>\n<td><code>GET /computers/list</code></td>\n<td>Mind Key или JWT</td>\n</tr>\n<tr>\n<td><code>POST /computers/:id/commands</code></td>\n<td>Mind Key или JWT</td>\n</tr>\n</tbody></table>\n<h2>Типовые паттерны</h2>\n<h3>Паттерн 1: одиночный LLM-агент</h3>\n<ol>\n<li>Зарегистрируйтесь один раз → получите JWT</li>\n<li>Создайте один mind → получите Mind Key</li>\n<li>LLM использует Mind Key для всего</li>\n</ol>\n<h3>Паттерн 2: агент с несколькими проектами</h3>\n<ol>\n<li>Зарегистрируйтесь один раз → получите JWT</li>\n<li>Создайте несколько mind (work, personal, project-x) → получите несколько Mind Key</li>\n<li>LLM загружает разные Mind Key в зависимости от контекста</li>\n</ol>\n<h3>Паттерн 3: командный обмен</h3>\n<ol>\n<li>Пользователь A создаёт mind → получает Mind Key A</li>\n<li>Пользователь A делится с пользователем B через JWT (<code>POST /sharing</code>)</li>\n<li>Пользователь B теперь может получить доступ через свой JWT</li>\n<li>Для доступа LLM пользователю B нужно создать свой Mind Key (или использовать A)</li>\n</ol>\n<h3>Паттерн 4: MCP-сервер</h3>\n<p>MCP-серверы всегда используют Mind Key (через переменную окружения <code>SYNAPSE_MIND_KEY</code>).\nОдин экземпляр MCP-сервера = один mind. Для доступа к нескольким mind запустите\nнесколько экземпляров MCP или реализуйте клиентское переключение mind.</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><code>mk_</code> + 36 символов</td>\n<td><code>mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789</code></td>\n</tr>\n<tr>\n<td>JWT</td>\n<td><code>eyJ</code> + base64</td>\n<td><code>eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...</code></td>\n</tr>\n<tr>\n<td>Computer Token</td>\n<td><code>ct_</code> + 36 символов</td>\n<td><code>ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789</code></td>\n</tr>\n</tbody></table>\n<h2>Следующие шаги</h2>\n<ul>\n<li><a href=\"/docs/getting-started/authentication\">Аутентификация</a> — полное руководство по аутентификации</li>\n<li><a href=\"/docs/api/user\">User &amp; Minds API</a> — эндпоинты под защитой JWT</li>\n<li><a href=\"/docs/api/memory\">Memory API</a> — эндпоинты под защитой Mind Key</li>\n</ul>\n","urls":{"html":"/docs/getting-started/mind-key-vs-jwt","text":"/docs/getting-started/mind-key-vs-jwt?format=text","json":"/docs/getting-started/mind-key-vs-jwt?format=json","llm":"/docs/getting-started/mind-key-vs-jwt?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}