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.

POST /api/v1/auth/login

Request Body

{
  "username": "admin",
  "password": "password123"
}

Response

{
  "success": true,
  "data": {
    "user": {
      "id": "user123",
      "username": "admin",
      "email": "admin@example.com",
      "role": "admin",
      "accountId": "acc123"
    },
    "tokens": {
      "accessToken": "eyJhbGciOiJIUzI1NiIs...",
      "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
      "expiresIn": 86400
    }
  }
}

Example

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.

POST /api/v1/auth/register

Request Body

{
  "username": "newuser",
  "email": "user@example.com",
  "password": "securepassword123",
  "fullName": "John Doe"
}

Response

{
  "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.

POST /api/v1/auth/refresh

Request Body

{
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

Response

{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 86400
  }
}

Logout

Invalidate current session.

POST /api/v1/auth/logout

Headers

Authorization: Bearer <access-token>

Response

{
  "success": true,
  "data": {
    "message": "Logged out successfully"
  }
}

Get Current User

Get authenticated user's profile.

GET /api/v1/auth/me

Headers

Authorization: Bearer <access-token>

Response

{
  "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.

PUT /api/v1/auth/profile

Headers

Authorization: Bearer <access-token>

Request Body

{
  "fullName": "John Smith",
  "email": "john.smith@example.com",
  "preferences": {
    "language": "en",
    "timezone": "America/New_York",
    "notifications": {
      "email": true,
      "push": false
    }
  }
}

Response

{
  "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.

POST /api/v1/auth/change-password

Headers

Authorization: Bearer <access-token>

Request Body

{
  "currentPassword": "oldpassword123",
  "newPassword": "newpassword456"
}

Response

{
  "success": true,
  "data": {
    "message": "Password changed successfully"
  }
}

Reset Password Request

Request password reset link.

POST /api/v1/auth/forgot-password

Request Body

{
  "email": "user@example.com"
}

Response

{
  "success": true,
  "data": {
    "message": "Password reset instructions sent to your email"
  }
}

Reset Password

Reset password using token.

POST /api/v1/auth/reset-password

Request Body

{
  "token": "reset-token-from-email",
  "newPassword": "newsecurepassword789"
}

Response

{
  "success": true,
  "data": {
    "message": "Password reset successfully"
  }
}

Error Responses

Invalid Credentials

{
  "success": false,
  "error": "Invalid username or password",
  "code": "INVALID_CREDENTIALS"
}

Token Expired

{
  "success": false,
  "error": "Token has expired",
  "code": "TOKEN_EXPIRED"
}

Account Locked

{
  "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

POST /api/v1/auth/2fa/enable

Verify 2FA

POST /api/v1/auth/2fa/verify

Disable 2FA

POST /api/v1/auth/2fa/disable

For detailed 2FA documentation, see the dedicated 2FA guide.