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

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

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

| Вы хотите... | Использовать |
|----------------|-----|
| Сохранять / отзывать воспоминания | Mind Key |
| Отправлять / опрашивать сообщения чата | Mind Key |
| Управлять задачами | Mind Key |
| Хранить скрипты | Mind Key |
| Регистрировать вебхуки | Mind Key |
| Управлять компьютерами | Mind Key (пользователь) / Computer Token (агент) |
| Зарегистрировать аккаунт | Нет (публичный) |
| Войти | Нет (публичный) |
| Создать / получить список / удалить mind | JWT |
| Поделиться mind с другим пользователем | JWT |
| Подписаться на web push-уведомления | JWT |
| Просмотреть журнал аудита | Mind Key |

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

> [!TIP]
> **Если действие касается данных одного mind → Mind Key.**
> **Если управляет аккаунтом или метаданными mind → JWT.**

## 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`
при активации установочного кода и привязан к конкретному зарегистрированному
компьютеру.

| Эндпоинт | Аутентификация |
|----------|------|
| `GET /computers/me/poll` | Computer Token |
| `POST /computers/me/commands/:cid/result` | Computer Token |
| `GET /computers/list` | Mind Key или JWT |
| `POST /computers/:id/commands` | Mind Key или JWT |

## Типовые паттерны

### Паттерн 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.

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

| Токен | Формат | Пример |
|-------|--------|---------|
| Mind Key | `mk_` + 36 символов | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |
| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| Computer Token | `ct_` + 36 символов | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |

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

- [Аутентификация](/docs/getting-started/authentication) — полное руководство по аутентификации
- [User & Minds API](/docs/api/user) — эндпоинты под защитой JWT
- [Memory API](/docs/api/memory) — эндпоинты под защитой Mind Key