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

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

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

| Ви хочете... | Використовуйте |
|----------------|-----|
| Зберігати / відкликати спогади | Mind Key |
| Надсилати / опитувати повідомлення чату | Mind Key |
| Керувати завданнями | Mind Key |
| Зберігати скрипти | Mind Key |
| Реєструвати webhooks | 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-сервера
- Інтеграцій 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` при активації коду встановлення та прив'язаний до
одного зареєстрованого комп'ютера.

| Кінцева точка | Auth |
|----------|------|
| `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 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-ів на боці клієнта.

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

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

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

- [Автентифікація](/docs/getting-started/authentication) — повний посібник з автентифікації
- [API користувачів та mind-ів](/docs/api/user) — кінцеві точки, захищені JWT
- [Memory API](/docs/api/memory) — кінцеві точки, захищені Mind Key