# Аутентификация и Mind Key

Synapse использует два способа аутентификации, каждый оптимизирован под свой
сценарий. Понимание различий необходимо для создания надёжных интеграций.

## Два способа аутентификации

| Способ | Сценарий | Лимит запросов | Срок действия |
|--------|----------|------------|--------|
| **Mind Key** | LLM-агенты, автоматизированные инструменты | Нет (заголовок) / 60/мин (query) | Бессрочно |
| **JWT** | Человеко-ориентированный UI, операции с аккаунтом | Нет | 7 дней |

## Mind Key (для агентов)

Mind Key — это токен API с областью действия на арендатора. Он аутентифицирует
данные одного mind (воспоминания, задачи, чат, скрипты и т. д.). Используйте его для:

- LLM-агентов, вызывающих API
- Фоновых скриптов автоматизации
- Конфигурации MCP-сервера
- Любой долгоживущей интеграции

### Аутентификация через заголовок (рекомендуется)

```bash
curl -H "Authorization: Bearer mk_yourMindKeyHere" \
     https://synapse.schaefer.zone/memory/recall
```

### Через query-параметр (для инструментов, работающих только с URL)

```bash
curl https://synapse.schaefer.zone/memory/recall?key=mk_yourMindKeyHere
```

> [!WARNING]
> Query-параметр `?key=` ограничен **60 запросами в минуту**.
> Заголовок Bearer не имеет лимита. Используйте заголовок всегда, когда клиент
> поддерживает пользовательские заголовки.

### Создание Mind Key

```bash
curl -X POST https://synapse.schaefer.zone/minds \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"name": "Work Mind", "description": "Project memories"}'
```

Ответ включает `mind_key` — **сохраните его немедленно**, он показывается только один раз.

### Получение списка своих mind

```bash
curl -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/minds
```

### Удаление mind (необратимо!)

```bash
curl -X DELETE -H "Authorization: Bearer YOUR_JWT" \
     https://synapse.schaefer.zone/minds/m_xyz789
```

## JWT (для людей)

JWT аутентифицирует **аккаунт пользователя**, а не конкретный mind. Используйте их для:

- Регистрации и входа в аккаунт
- Создания / получения списка / удаления mind
- Передачи mind другим пользователям
- Управления подписками Web Push

### Регистрация

```bash
curl -X POST https://synapse.schaefer.zone/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "secret"}'
```

Возвращает: `{ "jwt": "eyJ...", "user": {...} }`

### Вход

```bash
curl -X POST https://synapse.schaefer.zone/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "secret"}'
```

Возвращает: `{ "jwt": "eyJ...", "user": {...} }`

### Срок действия JWT

JWT истекает через **7 дней**. После истечения просто вызовите `/login` снова,
чтобы получить новый. Mind Key не истекает, поэтому существующие интеграции
агентов продолжают работать.

## Лучшие практики безопасности

> [!CRITICAL]
> - **Никогда не коммитьте Mind Key в git.** Используйте переменные окружения.
> - **Никогда не логируйте Mind Key.** Маскируйте их в логах (`mk_***...***xyz`).
> - **Ротируйте ключи** при подозрении на утечку (удалите mind, создайте новый).
> - **Используйте один mind на проект**, чтобы ограничить масштаб ущерба при утечке ключа.

### Паттерн переменных окружения

```bash
# .env (NEVER commit this file)
SYNAPSE_MIND_KEY=mk_yourMindKeyHere
SYNAPSE_URL=https://synapse.schaefer.zone
```

```typescript
// Node.js
const mindKey = process.env.SYNAPSE_MIND_KEY;
const url = process.env.SYNAPSE_URL;
await fetch(`${url}/memory/recall`, {
  headers: { Authorization: `Bearer ${mindKey}` },
});
```

### Конфигурация MCP-сервера

```json
{
  "mcpServers": {
    "synapse": {
      "command": "npx",
      "args": ["-y", "synapse-mcp-api@latest"],
      "env": {
        "SYNAPSE_MIND_KEY": "mk_yourMindKeyHere",
        "SYNAPSE_URL": "https://synapse.schaefer.zone"
      }
    }
  }
}
```

## Паттерн нескольких mind

У каждого пользователя может быть несколько mind. Типовые паттерны:

| Имя mind | Назначение |
|-----------|---------|
| `work` | Рабочие воспоминания |
| `personal` | Личные предпочтения, семья |
| `project-synapse` | Контекст конкретного проекта |
| `learning-german` | Прогресс обучения |
| `assistant-default` | Универсальный fallback |

Используйте разные Mind Key в разных LLM-сессиях, чтобы контексты были изолированы.

## Лимиты запросов

| Способ аутентификации | Лимит | Область |
|-------------|-------|-------|
| Mind Key (заголовок) | Нет | На mind |
| Mind Key (?key=) | 60/мин | На IP |
| JWT (заголовок) | Нет | На пользователя |
| Публичные эндпоинты | Нет | Глобально |

Заголовки лимитов (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After`)
включаются в ответы при применимости.

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

- [Mind Key против JWT](/docs/getting-started/mind-key-vs-jwt) — когда что использовать
- [Memory API](/docs/api/memory) — что можно делать с Mind Key
- [User API](/docs/api/user) — управление аккаунтом с JWT