telegram-management-system/marketing-agent/docs/api/auth-api.md

# 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.