Mind Key проти JWT — що коли?

У Synapse два токени автентифікації. Вибір неправильного призводить до помилок 401. Цей посібник дає чітку систему прийняття рішень.

Швидка таблиця рішень

Просте правило

Mind Key — токен доступу до даних

Mind Key надає доступ до даних одного mind-у. Це довготривалий токен, що ніколи не закінчується (поки mind не видалено). Ідеально для:

• LLM-агентів, що зберігають спогади між сесіями
• Фонових cron-завдань
• Конфігурації MCP-сервера
• Інтеграцій webhook-ів
• Мобільних додатків, що читають пам'ять

Що може Mind Key

• GET /memory/recall — читати всі спогади в цьому mind-і
• POST /memory — зберігати/оновлювати спогади
• GET /chat/poll — читати повідомлення чату
• POST /chat/reply — надсилати повідомлення чату
• GET /mind/tasks — список завдань
• POST /mind/task — створювати завдання
• POST /script — зберігати скрипти
• POST /webhooks — реєструвати webhooks
• POST /computers/:id/commands — ставити команди комп'ютера в чергу

Що Mind Key НЕ може

• Створювати / переглядати / видаляти mind-и (потрібен JWT)
• Ділитися mind-ом з іншим користувачем (потрібен JWT)
• Переглядати інформацію облікового запису (потрібен JWT)
• Підписуватися на web push (потрібен JWT)

JWT — токен керування обліковим записом

JWT автентифікує обліковий запис користувача. Він закінчується через 7 днів і використовується для операцій на рівні облікового запису, що охоплюють кілька mind-ів або залучають інших користувачів.

Що може JWT

• POST /minds — створити новий mind (повертає новий Mind Key)
• GET /minds — список усіх mind-ів цього користувача
• DELETE /minds/:id — видалити mind
• POST /sharing — поділитися mind-ом з іншим користувачем
• POST /push/subscribe — підписатися на web push-сповіщення
• GET /sharing — список спільних mind-ів

Що JWT НЕ може

• Читати / писати спогади (потрібен Mind Key)
• Надсилати повідомлення чату (потрібен Mind Key)
• Керувати завданнями (потрібен Mind Key)
• Реєструвати webhooks (потрібен Mind Key)

Особливий випадок: Computer Token

Кінцеві точки /computers/me/* (на боці агента, для screen-remote-agent) використовують третій тип токена: Computer Token. Цей токен повертається POST /computers/register при активації коду встановлення та прив'язаний до одного зареєстрованого комп'ютера.

Поширені шаблони

Шаблон 1: Один LLM-агент

1. Зареєструйтеся один раз → отримайте JWT
2. Створіть один mind → отримайте Mind Key
3. LLM використовує Mind Key для всього

Шаблон 2: Багатопроєктний агент

1. Зареєструйтеся один раз → отримайте JWT
2. Створіть кілька mind-ів (work, personal, project-x) → отримайте кілька Mind Keys
3. LLM завантажує різний Mind Key залежно від контексту

Шаблон 3: Командний доступ

1. Користувач A створює mind → отримує Mind Key A
2. Користувач A ділиться з Користувачем B через JWT (POST /sharing)
3. Користувач B тепер може доступатися через свій JWT
4. Для LLM-доступу Користувачу B потрібно створити власний Mind Key (або використати A)

Шаблон 4: MCP-сервер

MCP-сервери завжди використовують Mind Key (через змінну середовища SYNAPSE_MIND_KEY). Один екземпляр MCP-сервера = один mind. Для багато-mind доступу запустіть кілька екземплярів MCP або реалізуйте перемикання mind-ів на боці клієнта.

Шпаргалка форматів токенів

Наступні кроки

• Автентифікація — повний посібник з автентифікації
• API користувачів та mind-ів — кінцеві точки, захищені JWT
• Memory API — кінцеві точки, захищені Mind Key