# Автентифікація та Mind Keys

Synapse використовує два методи автентифікації, кожен оптимізований під свій
варіант використання. Розуміння різниці є необхідним для побудови надійних
інтеграцій.

## Два методи автентифікації

| Метод | Варіант використання | Обмеження частоти | Термін дії |
|--------|----------|------------|--------|
| **Mind Key** | LLM-агенти, інструменти автоматизації | Немає (заголовок) / 60 хв (запит) | Ніколи |
| **JWT** | Людський інтерфейс, операції облікового запису | Немає | 7 днів |

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

Mind Key — це API-токен, прив'язаний до тенанта. Він автентифікує дані одного
mind-у (спогади, завдання, чат, скрипти тощо). Використовуйте для:

- LLM-агентів, що викликають API
- Фонових скриптів автоматизації
- Конфігурації MCP-сервера
- Будь-якої довготривалої інтеграції

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

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

### Параметр запиту (для URL-only інструментів)

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

> [!WARNING]
> Параметр запиту `?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 днів**. Коли JWT закінчується, просто викличте `/login`
знову, щоб отримати новий. Mind Key ніколи не закінчується, тому наявні інтеграції
агентів продовжують працювати.

## Найкращі практики безпеки

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

### Шаблон змінних середовища

```bash
# .env (НІКОЛИ не комітьте цей файл)
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 Keys для різних сесій 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
- [API користувачів](/docs/api/user) — керування обліковим записом з JWT