Mind Key против JWT — что когда?

В Synapse два типа токенов аутентификации. Выбор неверного приводит к ошибкам 401. Это руководство даёт чёткую основу для выбора.

Краткая таблица решений

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

Mind Key — токен доступа к данным

Mind Key даёт доступ к данным одного mind. Это долгоживущий токен, который не истекает (пока mind не удалён). Идеально для:

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

Что может Mind Key

• GET /memory/recall — читать все воспоминания этого mind
• POST /memory — сохранять/обновлять воспоминания
• GET /chat/poll — читать сообщения чата
• POST /chat/reply — отправлять сообщения чата
• GET /mind/tasks — получать список задач
• POST /mind/task — создавать задачи
• POST /script — хранить скрипты
• POST /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)
• Регистрировать вебхуки (нужен 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 Key
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.

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

Следующие шаги

• Аутентификация — полное руководство по аутентификации
• User & Minds API — эндпоинты под защитой JWT
• Memory API — эндпоинты под защитой Mind Key