Document Telegram first-class auth

03 - API Reference/Authentication API.md

@@ -121,6 +121,37 @@ Two distinct identities are involved: a [[User]] (`models/User.ts`) and a [[Temp
 - Pushes refresh token onto `user.refreshTokens`.
 - Redis session start via `sessionService`.
 
+### POST /api/auth/telegram
+
+**Description:** First-class Telegram authentication. Accepts Telegram Mini App `initData` or a Telegram Login Widget payload, verifies the Telegram signature server-side, and signs the user into Amanat without requiring email or password.
+**Auth required:** No
+**Request body:**
+```ts
+// Mini App
+{ initData: string; role?: "buyer" | "seller" }
+
+// Login Widget
+{ loginWidget: { id: string; first_name?: string; username?: string; auth_date: string; hash: string }; role?: "buyer" | "seller" }
+```
+**Response 200/201:**
+```json
+{
+  "success": true,
+  "data": {
+    "user": { "_id": "...", "authProvider": "telegram", "telegramVerified": true },
+    "tokens": { "accessToken": "...", "refreshToken": "..." },
+    "isNewUser": true,
+    "telegram": { "userId": "10001", "username": "alice", "source": "miniapp" }
+  }
+}
+```
+**Errors:** `400` missing payload, `401` invalid/stale signature, `403` blocked Telegram account or inactive Amanat account, `409 TELEGRAM_REPLAY` reused Mini App `initData`, `429` rate-limited.
+**Side effects:**
+- Creates a Telegram-only [[User]] when no active `TelegramLink` exists. The user has no email, `authProvider: "telegram"`, and `telegramVerified: true`.
+- Upserts `TelegramLink` for the Telegram ID and updates last-seen metadata.
+- Stores the refresh token on the user document.
+- Does not expose phone numbers; Telegram phone data is not requested or persisted.
+
 ### POST /api/auth/refresh-token
 
 **Description:** Exchanges a refresh token for a new access token. Rotates the refresh token.