From 6586ef34eaf9a511230427c0b976b3c9c67a9fd9 Mon Sep 17 00:00:00 2001
From: Kavalar <apuc06@mail.ru>
Date: Sat, 26 Sep 2026 19:33:41 +0300
Subject: [PATCH] docs: API - JWT 1 month + refresh, bot service token,
 decisions

---
 docs/tech-design/02-api.md | 38 ++++++++++++++++++++++++++++++--------
 1 file changed, 30 insertions(+), 8 deletions(-)

diff --git a/docs/tech-design/02-api.md b/docs/tech-design/02-api.md
index 6382192..39dddbe 100644
--- a/docs/tech-design/02-api.md
+++ b/docs/tech-design/02-api.md
@@ -67,14 +67,30 @@
 // request
 { "token": "...", "messenger_type": "telegram", "messenger_id": "123456" }
 // response 200
-{ "access_token": "jwt", "expires_at": "...", "user": { "id": 1, "full_name": "..." } }
+{
+  "access_token": "jwt",
+  "refresh_token": "opaque",
+  "expires_at": "...",
+  "user": { "id": 1, "full_name": "..." }
+}
 ```
 
 **Ошибки:** `409 link_already_used` → «Ссылка уже была использована. Запросите новую у координатора».
 
-### 2.3. `POST /auth/logout` — завершить сессию
+### 2.3. `POST /auth/refresh` — обновить access-токен
 
-### 2.4. `GET /auth/me` — текущий пользователь
+```json
+// request
+{ "refresh_token": "opaque" }
+// response 200
+{ "access_token": "jwt", "refresh_token": "opaque", "expires_at": "..." }
+```
+
+**Правило:** refresh-токен ротируемый (при обновлении выдаётся новый, старый инвалидируется).
+
+### 2.4. `POST /auth/logout` — завершить сессию
+
+### 2.5. `GET /auth/me` — текущий пользователь
 
 ```json
 {
@@ -334,12 +350,18 @@
 
 ---
 
-## 17. Открытые вопросы
+## 17. Принятые решения и открытые вопросы
 
-1. **Формат JWT** — срок жизни access-токена и нужен ли refresh.
-2. **Сервисный токен бота** — отдельный тип или роль `system`.
-3. **Presigned URL** — срок жизни ссылок на скачивание артефактов.
-4. **Вебхуки MAX** — уточнить после проверки MAX Bot API.
+**Принято:**
+
+1. **JWT** — access-токен сроком **1 месяц** + **refresh-токен** (ротируемый). Эндпоинт `POST /auth/refresh`.
+   - *Рекомендация по безопасности:* для продакшена желательно сократить access-токен (например, до 1 часа) и держать длинным refresh; при текущем решении компромисс — короткий срок хранения сессий и журналирование.
+2. **Сервисный токен бота** — отдельный тип токена (системный актор), не роль пользователя.
+3. **Вебхуки MAX** — проверяем после подтверждения возможностей MAX Bot API.
+
+**Открыто:**
+
+4. **Presigned URL** — срок жизни ссылок на скачивание артефактов (предложение: 15 минут).
 
 ---