Initial commit: Telegram Management System

Full-stack web application for Telegram management
- Frontend: Vue 3 + Vben Admin
- Backend: NestJS
- Features: User management, group broadcast, statistics

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

marketing-agent/docs/api/auth-api.md

@@ -0,0 +1,389 @@
+# Authentication API
+
+The Authentication API manages user authentication, session management, and access control.
+
+## Endpoints
+
+### Login
+
+Authenticate a user and receive access tokens.
+
+```http
+POST /api/v1/auth/login
+```
+
+#### Request Body
+
+```json
+{
+  "username": "admin",
+  "password": "password123"
+}
+```
+
+#### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "user": {
+      "id": "user123",
+      "username": "admin",
+      "email": "admin@example.com",
+      "role": "admin",
+      "accountId": "acc123"
+    },
+    "tokens": {
+      "accessToken": "eyJhbGciOiJIUzI1NiIs...",
+      "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
+      "expiresIn": 86400
+    }
+  }
+}
+```
+
+#### Example
+
+```bash
+curl -X POST http://localhost:3000/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{
+    "username": "admin",
+    "password": "password123"
+  }'
+```
+
+### Register
+
+Create a new user account.
+
+```http
+POST /api/v1/auth/register
+```
+
+#### Request Body
+
+```json
+{
+  "username": "newuser",
+  "email": "user@example.com",
+  "password": "securepassword123",
+  "fullName": "John Doe"
+}
+```
+
+#### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "user": {
+      "id": "user456",
+      "username": "newuser",
+      "email": "user@example.com",
+      "role": "user",
+      "accountId": "acc456"
+    },
+    "message": "Registration successful. Please verify your email."
+  }
+}
+```
+
+### Refresh Token
+
+Refresh access token using refresh token.
+
+```http
+POST /api/v1/auth/refresh
+```
+
+#### Request Body
+
+```json
+{
+  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
+}
+```
+
+#### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
+    "expiresIn": 86400
+  }
+}
+```
+
+### Logout
+
+Invalidate current session.
+
+```http
+POST /api/v1/auth/logout
+```
+
+#### Headers
+
+```
+Authorization: Bearer <access-token>
+```
+
+#### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "message": "Logged out successfully"
+  }
+}
+```
+
+### Get Current User
+
+Get authenticated user's profile.
+
+```http
+GET /api/v1/auth/me
+```
+
+#### Headers
+
+```
+Authorization: Bearer <access-token>
+```
+
+#### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "id": "user123",
+    "username": "admin",
+    "email": "admin@example.com",
+    "fullName": "Admin User",
+    "role": "admin",
+    "accountId": "acc123",
+    "permissions": [
+      "campaigns.create",
+      "campaigns.update",
+      "campaigns.delete",
+      "users.manage"
+    ],
+    "createdAt": "2024-01-01T00:00:00Z",
+    "lastLogin": "2024-01-20T10:30:00Z"
+  }
+}
+```
+
+### Update Profile
+
+Update authenticated user's profile.
+
+```http
+PUT /api/v1/auth/profile
+```
+
+#### Headers
+
+```
+Authorization: Bearer <access-token>
+```
+
+#### Request Body
+
+```json
+{
+  "fullName": "John Smith",
+  "email": "john.smith@example.com",
+  "preferences": {
+    "language": "en",
+    "timezone": "America/New_York",
+    "notifications": {
+      "email": true,
+      "push": false
+    }
+  }
+}
+```
+
+#### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "message": "Profile updated successfully",
+    "user": {
+      "id": "user123",
+      "username": "admin",
+      "email": "john.smith@example.com",
+      "fullName": "John Smith"
+    }
+  }
+}
+```
+
+### Change Password
+
+Change authenticated user's password.
+
+```http
+POST /api/v1/auth/change-password
+```
+
+#### Headers
+
+```
+Authorization: Bearer <access-token>
+```
+
+#### Request Body
+
+```json
+{
+  "currentPassword": "oldpassword123",
+  "newPassword": "newpassword456"
+}
+```
+
+#### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "message": "Password changed successfully"
+  }
+}
+```
+
+### Reset Password Request
+
+Request password reset link.
+
+```http
+POST /api/v1/auth/forgot-password
+```
+
+#### Request Body
+
+```json
+{
+  "email": "user@example.com"
+}
+```
+
+#### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "message": "Password reset instructions sent to your email"
+  }
+}
+```
+
+### Reset Password
+
+Reset password using token.
+
+```http
+POST /api/v1/auth/reset-password
+```
+
+#### Request Body
+
+```json
+{
+  "token": "reset-token-from-email",
+  "newPassword": "newsecurepassword789"
+}
+```
+
+#### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "message": "Password reset successfully"
+  }
+}
+```
+
+## Error Responses
+
+### Invalid Credentials
+
+```json
+{
+  "success": false,
+  "error": "Invalid username or password",
+  "code": "INVALID_CREDENTIALS"
+}
+```
+
+### Token Expired
+
+```json
+{
+  "success": false,
+  "error": "Token has expired",
+  "code": "TOKEN_EXPIRED"
+}
+```
+
+### Account Locked
+
+```json
+{
+  "success": false,
+  "error": "Account is locked due to multiple failed login attempts",
+  "code": "ACCOUNT_LOCKED",
+  "details": {
+    "lockedUntil": "2024-01-20T11:00:00Z"
+  }
+}
+```
+
+## Security Best Practices
+
+1. **Token Storage**: Store tokens securely in httpOnly cookies or secure storage
+2. **Token Rotation**: Refresh tokens regularly to minimize exposure
+3. **Password Requirements**: 
+   - Minimum 8 characters
+   - At least one uppercase letter
+   - At least one number
+   - At least one special character
+4. **Rate Limiting**: Login attempts are rate-limited to prevent brute force attacks
+5. **Two-Factor Authentication**: Available for enhanced security (see 2FA endpoints)
+
+## Two-Factor Authentication (2FA)
+
+### Enable 2FA
+
+```http
+POST /api/v1/auth/2fa/enable
+```
+
+### Verify 2FA
+
+```http
+POST /api/v1/auth/2fa/verify
+```
+
+### Disable 2FA
+
+```http
+POST /api/v1/auth/2fa/disable
+```
+
+For detailed 2FA documentation, see the dedicated 2FA guide.