# User Profile Management Service

**Author**: Josh S. Sakweli, Backend Lead Team  
**Last Updated**: 2025-09-23  
**Version**: v1.0

**Short Description**: The User Profile Management Service handles user profile updates, security settings, account verification, password changes, and account management for the NextGate social commerce platform. This service provides comprehensive profile management with security controls, two-factor authentication, and account verification capabilities.

**Hints**: 
- All endpoints require JWT Bearer token authentication
- Password changes trigger automatic logout and require re-authentication
- Username changes require immediate re-login with new credentials
- Email/phone updates require OTP verification for security
- Profile picture URLs must be valid HTTPS image URLs (max 5 pictures)
- Security strength is calculated based on verification status and 2FA
- Account deactivation locks the account instead of deleting data
- Rate limiting applies to OTP verification requests (5 per 10-minute window)

---

## Endpoints

## 1. Get Current User Profile
**Purpose**: Retrieve complete profile information for the authenticated user

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `https://apinexgate.glueauth.com/api/v1/profile/me`

**Access Level**: 🔒 Protected (Requires JWT Bearer token)

**Authentication**: Bearer Token (JWT access token required)

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer {access_token} |
| Content-Type | string | Yes | Must be "application/json" |

**Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Profile retrieved successfully",
  "action_time": "2025-09-23T10:30:00",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "userName": "johndoe-a1B2c3D",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Michael",
    "email": "john.doe@example.com",
    "phoneNumber": "+255712345678",
    "isVerified": true,
    "isEmailVerified": true,
    "isPhoneVerified": false,
    "isTwoFactorEnabled": false,
    "isAccountLocked": false,
    "createdAt": "2025-09-23T10:00:00",
    "editedAt": "2025-09-23T10:30:00",
    "roles": ["ROLE_NORMAL_USER"],
    "profilePictureUrls": [
      "https://files.nextgate.com/bucket-uuid/profile/avatar1.jpg",
      "https://files.nextgate.com/bucket-uuid/profile/avatar2.jpg"
    ],
    "securityStrength": {
      "score": 65,
      "level": "MEDIUM",
      "description": "Your account security is good but can be improved",
      "recommendations": [
        "Verify your phone number",
        "Enable two-factor authentication"
      ]
    }
  }
}
```

**Response Fields**:
| Field | Description |
|-------|-------------|
| success | Boolean indicating operation success |
| httpStatus | HTTP status code as string |
| message | Success message |
| action_time | ISO 8601 timestamp of response generation |
| data.id | Unique user identifier (UUID) |
| data.userName | User's unique username |
| data.firstName | User's first name |
| data.lastName | User's last name |
| data.middleName | User's middle name |
| data.email | User's email address |
| data.phoneNumber | User's phone number in international format |
| data.isVerified | Overall account verification status |
| data.isEmailVerified | Email verification status |
| data.isPhoneVerified | Phone number verification status |
| data.isTwoFactorEnabled | Two-factor authentication status |
| data.isAccountLocked | Account lock status |
| data.createdAt | Account creation timestamp |
| data.editedAt | Last profile modification timestamp |
| data.roles | Array of user roles/permissions |
| data.profilePictureUrls | Array of profile picture URLs (max 5) |
| data.securityStrength.score | Security score from 0-100 |
| data.securityStrength.level | Security level (WEAK, MEDIUM, STRONG, VERY_WEAK) |
| data.securityStrength.description | Human-readable security assessment |
| data.securityStrength.recommendations | Array of security improvement suggestions |

**Error Responses**:
- `401 Unauthorized`: Missing or invalid JWT token
- `404 Not Found`: User account not found
- `500 Internal Server Error`: Server-side processing errors

---

## 2. Update Basic Profile Information
**Purpose**: Update user's basic profile information including username, names, email, phone, and profile pictures

**Endpoint**: <span style="background-color: #17a2b8; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span> `https://apinexgate.glueauth.com/api/v1/profile/update-basic-info`

**Access Level**: 🔒 Protected (Requires JWT Bearer token) ⚠️ **Username changes require re-authentication**

**Authentication**: Bearer Token (JWT access token required)

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer {access_token} |
| Content-Type | string | Yes | Must be "application/json" |

**Request JSON Sample**:
```json
{
  "userName": "johnsmith",
  "firstName": "John",
  "lastName": "Smith",
  "middleName": "Michael",
  "email": "john.smith@example.com",
  "phoneNumber": "+255723456789",
  "profilePictureUrls": [
    "https://files.nextgate.com/bucket-uuid/profile/new-avatar.jpg",
    "https://files.nextgate.com/bucket-uuid/profile/banner.jpg"
  ]
}
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| userName | string | No | New username (triggers re-authentication if changed) | 3-30 chars, start with letter, alphanumeric + underscore/hyphen only |
| firstName | string | No | User's first name | 1-30 characters |
| lastName | string | No | User's last name | 1-30 characters |
| middleName | string | No | User's middle name | Max 30 characters |
| email | string | No | User's email address (requires re-verification if changed) | Valid email format |
| phoneNumber | string | No | Phone number (requires re-verification if changed) | E.164 international format (+1234567890) |
| profilePictureUrls | array | No | Array of profile picture URLs | Max 5 URLs, valid HTTPS image URLs only |

**Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Username changed successfully! You will be logged out automatically. Please login again with your new username.",
  "action_time": "2025-09-23T10:35:00",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "userName": "johnsmith",
    "firstName": "John",
    "lastName": "Smith",
    "middleName": "Michael",
    "email": "john.smith@example.com",
    "phoneNumber": "+255723456789",
    "isVerified": true,
    "isEmailVerified": false,
    "isPhoneVerified": false,
    "isTwoFactorEnabled": false,
    "isAccountLocked": false,
    "createdAt": "2025-09-23T10:00:00",
    "editedAt": "2025-09-23T10:35:00",
    "roles": ["ROLE_NORMAL_USER"],
    "profilePictureUrls": [
      "https://files.nextgate.com/bucket-uuid/profile/new-avatar.jpg",
      "https://files.nextgate.com/bucket-uuid/profile/banner.jpg"
    ],
    "securityStrength": {
      "score": 40,
      "level": "WEAK",
      "description": "Your account security needs improvement",
      "recommendations": [
        "Verify your email address",
        "Verify your phone number",
        "Enable two-factor authentication"
      ]
    }
  }
}
```

**Response Fields**:
| Field | Description |
|-------|-------------|
| success | Boolean indicating operation success |
| httpStatus | HTTP status code as string |
| message | Success message (special message if username changed) |
| action_time | ISO 8601 timestamp of response generation |
| data | Updated UserProfileResponse object with complete profile data |

**Error Responses**:
- `400 Bad Request`: Invalid input data or validation errors
- `401 Unauthorized`: Missing or invalid JWT token
- `409 Conflict`: Username or email already taken
- `422 Unprocessable Entity`: Validation errors (reserved username, invalid format)
- `500 Internal Server Error`: Server-side processing errors

---

## 3. Change Password
**Purpose**: Change user's password with current password verification and strength validation

**Endpoint**: <span style="background-color: #17a2b8; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">PUT</span> `https://apinexgate.glueauth.com/api/v1/profile/change-password`

**Access Level**: 🔒 Protected (Requires JWT Bearer token) ⚠️ **Triggers automatic logout**

**Authentication**: Bearer Token (JWT access token required)

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer {access_token} |
| Content-Type | string | Yes | Must be "application/json" |

**Request JSON Sample**:
```json
{
  "currentPassword": "OldPassword123!",
  "newPassword": "NewSecurePass456@",
  "confirmPassword": "NewSecurePass456@"
}
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| currentPassword | string | Yes | User's current password | Must match current password |
| newPassword | string | Yes | New password | Min 8 chars, uppercase, lowercase, digit, special character |
| confirmPassword | string | Yes | Confirmation of new password | Must match newPassword exactly |

**Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Password changed successfully",
  "action_time": "2025-09-23T10:40:00",
  "data": null
}
```

**Response Fields**:
| Field | Description |
|-------|-------------|
| success | Boolean indicating operation success |
| httpStatus | HTTP status code as string |
| message | Success message confirming password change |
| action_time | ISO 8601 timestamp of response generation |
| data | Always null for password change operations |

**Error Responses**:
- `400 Bad Request`: Invalid password format or passwords don't match
- `401 Unauthorized`: Missing or invalid JWT token or incorrect current password
- `422 Unprocessable Entity`: Password strength requirements not met
- `500 Internal Server Error`: Server-side processing errors

---

## 4. Validate Username Availability
**Purpose**: Check if a username is available and valid, with suggestions if taken

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `https://apinexgate.glueauth.com/api/v1/profile/validate-username/{username}`

**Access Level**: 🔒 Protected (Requires JWT Bearer token)

**Authentication**: Bearer Token (JWT access token required)

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer {access_token} |
| Content-Type | string | Yes | Must be "application/json" |

**Path Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| username | string | Yes | Username to validate | 3-30 characters, alphanumeric + underscore/hyphen |

**Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Username validation completed",
  "action_time": "2025-09-23T10:45:00",
  "data": {
    "available": false,
    "valid": true,
    "message": "This username is already taken",
    "suggestions": [
      "johnsmith1",
      "johnsmith2",
      "johnsmithuser",
      "johnsmith2024",
      "johnsmithpro"
    ],
    "details": {
      "correctLength": true,
      "validFormat": true,
      "notReserved": true,
      "notTaken": false,
      "formatRequirement": "Username must start with a letter and be 3-30 characters long"
    }
  }
}
```

**Response Fields**:
| Field | Description |
|-------|-------------|
| success | Boolean indicating operation success |
| httpStatus | HTTP status code as string |
| message | Success message |
| action_time | ISO 8601 timestamp of response generation |
| data.available | Boolean indicating if username is available for use |
| data.valid | Boolean indicating if username format is valid |
| data.message | Detailed validation message |
| data.suggestions | Array of alternative username suggestions (if taken) |
| data.details.correctLength | Boolean indicating if length requirements are met |
| data.details.validFormat | Boolean indicating if format requirements are met |
| data.details.notReserved | Boolean indicating if username is not reserved |
| data.details.notTaken | Boolean indicating if username is not already taken |
| data.details.formatRequirement | String describing format requirements |

**Error Responses**:
- `400 Bad Request`: Invalid username parameter
- `401 Unauthorized`: Missing or invalid JWT token
- `500 Internal Server Error`: Server-side processing errors

---

## 5. Request Email Verification
**Purpose**: Send OTP to user's email for email verification

**Endpoint**: <span style="background-color: #fd7e14; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `https://apinexgate.glueauth.com/api/v1/profile/request-email-verification`

**Access Level**: 🔒 Protected (Requires JWT Bearer token)

**Authentication**: Bearer Token (JWT access token required)

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer {access_token} |
| Content-Type | string | Yes | Must be "application/json" |

**Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Email verification OTP sent successfully",
  "action_time": "2025-09-23T10:50:00",
  "data": {
    "tempToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "message": "Verification email sent successfully",
    "expireAt": "2025-09-23T11:00:00",
    "email": "jo***@example.com"
  }
}
```

**Response Fields**:
| Field | Description |
|-------|-------------|
| success | Boolean indicating operation success |
| httpStatus | HTTP status code as string |
| message | Success message |
| action_time | ISO 8601 timestamp of response generation |
| data.tempToken | JWT temporary token for OTP verification |
| data.message | Specific message about email sending |
| data.expireAt | ISO 8601 timestamp when temp token expires |
| data.email | Masked email address for privacy |

**Error Responses**:
- `400 Bad Request`: Email already verified
- `401 Unauthorized`: Missing or invalid JWT token
- `429 Too Many Requests`: Rate limit exceeded for OTP requests
- `500 Internal Server Error`: Email sending or server errors

---

## 6. Verify Email
**Purpose**: Complete email verification using OTP code

**Endpoint**: <span style="background-color: #fd7e14; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `https://apinexgate.glueauth.com/api/v1/profile/verify-email`

**Access Level**: 🔒 Protected (Requires JWT Bearer token)

**Authentication**: Bearer Token (JWT access token required)

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer {access_token} |
| Content-Type | string | Yes | Must be "application/json" |

**Request JSON Sample**:
```json
{
  "tempToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "otpCode": "123456"
}
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| tempToken | string | Yes | Temporary token from email verification request | Must be valid non-expired temp token |
| otpCode | string | Yes | 6-digit OTP code from email | Must be exactly 6 digits (\\d{6}) |

**Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Email verified successfully",
  "action_time": "2025-09-23T10:55:00",
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "userName": "johndoe-a1B2c3D",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Michael",
    "email": "john.doe@example.com",
    "phoneNumber": "+255712345678",
    "isVerified": true,
    "isEmailVerified": true,
    "isPhoneVerified": false,
    "isTwoFactorEnabled": false,
    "isAccountLocked": false,
    "createdAt": "2025-09-23T10:00:00",
    "editedAt": "2025-09-23T10:55:00",
    "roles": ["ROLE_NORMAL_USER"],
    "profilePictureUrls": [],
    "securityStrength": {
      "score": 75,
      "level": "MEDIUM",
      "description": "Your account security is good but can be improved",
      "recommendations": [
        "Verify your phone number",
        "Enable two-factor authentication"
      ]
    }
  }
}
```

**Response Fields**:
| Field | Description |
|-------|-------------|
| success | Boolean indicating operation success |
| httpStatus | HTTP status code as string |
| message | Success message confirming email verification |
| action_time | ISO 8601 timestamp of response generation |
| data | Updated UserProfileResponse object with email verification status |

**Error Responses**:
- `400 Bad Request`: Invalid OTP format or missing required fields
- `401 Unauthorized`: Missing or invalid JWT token or temp token
- `422 Unprocessable Entity`: OTP verification failed or token expired
- `500 Internal Server Error`: Server-side processing errors

---

## 7. Get Security Information
**Purpose**: Retrieve detailed security settings and account security strength

**Endpoint**: <span style="background-color: #28a745; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `https://apinexgate.glueauth.com/api/v1/profile/security-info`

**Access Level**: 🔒 Protected (Requires JWT Bearer token)

**Authentication**: Bearer Token (JWT access token required)

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer {access_token} |
| Content-Type | string | Yes | Must be "application/json" |

**Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Security information retrieved successfully",
  "action_time": "2025-09-23T11:00:00",
  "data": {
    "isEmailVerified": true,
    "isPhoneVerified": false,
    "isTwoFactorEnabled": false,
    "isAccountLocked": false,
    "lastPasswordChange": "2025-09-23T10:40:00",
    "accountCreatedAt": "2025-09-23T10:00:00",
    "roles": ["ROLE_NORMAL_USER"],
    "securityStrength": {
      "score": 75,
      "level": "MEDIUM",
      "description": "Your account security is good but can be improved",
      "recommendations": [
        "Verify your phone number",
        "Enable two-factor authentication"
      ]
    }
  }
}
```

**Response Fields**:
| Field | Description |
|-------|-------------|
| success | Boolean indicating operation success |
| httpStatus | HTTP status code as string |
| message | Success message |
| action_time | ISO 8601 timestamp of response generation |
| data.isEmailVerified | Email verification status |
| data.isPhoneVerified | Phone verification status |
| data.isTwoFactorEnabled | Two-factor authentication status |
| data.isAccountLocked | Account lock status |
| data.lastPasswordChange | Timestamp of last password change |
| data.accountCreatedAt | Account creation timestamp |
| data.roles | Array of user roles/permissions |
| data.securityStrength | Detailed security strength analysis |

**Error Responses**:
- `401 Unauthorized`: Missing or invalid JWT token
- `404 Not Found`: User account not found
- `500 Internal Server Error`: Server-side processing errors

---

## 8. Enable Two-Factor Authentication
**Purpose**: Enable two-factor authentication for enhanced account security

**Endpoint**: <span style="background-color: #fd7e14; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `https://apinexgate.glueauth.com/api/v1/profile/enable-2fa`

**Access Level**: 🔒 Protected (Requires JWT Bearer token)

**Authentication**: Bearer Token (JWT access token required)

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer {access_token} |
| Content-Type | string | Yes | Must be "application/json" |

**Request JSON Sample**:
```json
{
  "password": "CurrentPassword123!"
}
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| password | string | Yes | User's current password for verification | Must match current password |

**Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Two-factor authentication enabled successfully",
  "action_time": "2025-09-23T11:05:00",
  "data": null
}
```

**Response Fields**:
| Field | Description |
|-------|-------------|
| success | Boolean indicating operation success |
| httpStatus | HTTP status code as string |
| message | Success message confirming 2FA enablement |
| action_time | ISO 8601 timestamp of response generation |
| data | Always null for 2FA operations |

**Error Responses**:
- `400 Bad Request`: Missing password or 2FA already enabled
- `401 Unauthorized`: Missing or invalid JWT token or incorrect password
- `422 Unprocessable Entity`: Invalid password verification
- `500 Internal Server Error`: Server-side processing errors

---

## 9. Disable Two-Factor Authentication
**Purpose**: Disable two-factor authentication with password verification

**Endpoint**: <span style="background-color: #fd7e14; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">POST</span> `https://apinexgate.glueauth.com/api/v1/profile/disable-2fa`

**Access Level**: 🔒 Protected (Requires JWT Bearer token)

**Authentication**: Bearer Token (JWT access token required)

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer {access_token} |
| Content-Type | string | Yes | Must be "application/json" |

**Request JSON Sample**:
```json
{
  "password": "CurrentPassword123!"
}
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| password | string | Yes | User's current password for verification | Must match current password |

**Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Two-factor authentication disabled successfully",
  "action_time": "2025-09-23T11:10:00",
  "data": null
}
```

**Response Fields**:
| Field | Description |
|-------|-------------|
| success | Boolean indicating operation success |
| httpStatus | HTTP status code as string |
| message | Success message confirming 2FA disablement |
| action_time | ISO 8601 timestamp of response generation |
| data | Always null for 2FA operations |

**Error Responses**:
- `400 Bad Request`: Missing password or 2FA not enabled
- `401 Unauthorized`: Missing or invalid JWT token or incorrect password
- `422 Unprocessable Entity`: Invalid password verification
- `500 Internal Server Error`: Server-side processing errors

---

## 10. Deactivate Account
**Purpose**: Deactivate (soft delete) user account with password verification

**Endpoint**: <span style="background-color: #dc3545; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">DELETE</span> `https://apinexgate.glueauth.com/api/v1/profile/deactivate`

**Access Level**: 🔒 Protected (Requires JWT Bearer token) ⚠️ **Irreversible action**

**Authentication**: Bearer Token (JWT access token required)

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer {access_token} |
| Content-Type | string | Yes | Must be "application/json" |

**Request JSON Sample**:
```json
{
  "password": "CurrentPassword123!",
  "reason": "No longer using the platform"
}
```

**Request Body Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| password | string | Yes | User's current password for verification | Must match current password |
| reason | string | No | Optional reason for deactivation | Max 500 characters |

**Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Account deactivated successfully",
  "action_time": "2025-09-23T11:15:00",
  "data": null
}
```

**Response Fields**:
| Field | Description |
|-------|-------------|
| success | Boolean indicating operation success |
| httpStatus | HTTP status code as string |
| message | Success message confirming account deactivation |
| action_time | ISO 8601 timestamp of response generation |
| data | Always null for deactivation operations |

**Error Responses**:
- `400 Bad Request`: Missing password or invalid reason length
- `401 Unauthorized`: Missing or invalid JWT token or incorrect password
- `422 Unprocessable Entity`: Invalid password verification
- `500 Internal Server Error`: Server-side processing errors

---
## 11. Get My Profile Summary (Modified from Get Current User Profile)

**Purpose**: Retrieve the authenticated user's profile summary with stats

**Endpoint**: <span style="background-color: #61affe; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/api/v1/profile/me`

**Access Level**: 🔒 Protected (Requires Authentication)

**Authentication**: Bearer Token

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer token for authentication |

**Success Response JSON Sample**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Profile retrieved successfully",
  "action_time": "2025-12-29T17:00:00",
  "data": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "userName": "john_doe",
    "firstName": "John",
    "lastName": "Doe",
    "profilePictureUrl": "https://storage.example.com/profiles/john.jpg",
    "bio": "Tech enthusiast | Entrepreneur | Dar es Salaam",
    "location": "Dar es Salaam, Tanzania",
    "isVerified": true,
    "followersCount": 1250,
    "followingCount": 340,
    "postsCount": 85,
    "shopsCount": 2,
    "eventsCount": 5,
    "createdAt": "2024-03-15T08:00:00",
    "isOwnProfile": true,
    "relationship": null
  }
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| userId | Unique identifier of the user |
| userName | Username handle |
| firstName | User's first name |
| lastName | User's last name |
| profilePictureUrl | URL to profile picture |
| bio | User's bio/description |
| location | User's location |
| isVerified | Whether user is verified |
| followersCount | Number of followers |
| followingCount | Number of users following |
| postsCount | Number of published posts |
| shopsCount | Number of active shops owned |
| eventsCount | Number of published events created |
| createdAt | Account creation date |
| isOwnProfile | Always `true` for this endpoint |
| relationship | Always `null` for own profile |

**Error Response JSON Sample**:
```json
{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "User not authenticated",
  "action_time": "2025-12-29T17:00:00",
  "data": null
}
```

**Standard Error Types**:
- `401 UNAUTHORIZED`: Missing or invalid authentication token

---

## 12. Get User Profile by ID

**Purpose**: Retrieve a user's profile summary by their unique ID

**Endpoint**: <span style="background-color: #61affe; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/api/v1/profile/id/{userId}`

**Access Level**: 🔒 Protected (Requires Authentication)

**Authentication**: Bearer Token

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer token for authentication |

**Path Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| userId | UUID | Yes | Unique identifier of the user | Valid UUID format |

**Success Response JSON Sample (Viewing Other User)**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Profile retrieved successfully",
  "action_time": "2025-12-29T17:00:00",
  "data": {
    "userId": "660e8400-e29b-41d4-a716-446655440001",
    "userName": "jane_smith",
    "firstName": "Jane",
    "lastName": "Smith",
    "profilePictureUrl": "https://storage.example.com/profiles/jane.jpg",
    "bio": "Fashion designer | Shop owner | Arusha",
    "location": "Arusha, Tanzania",
    "isVerified": true,
    "followersCount": 5420,
    "followingCount": 180,
    "postsCount": 320,
    "shopsCount": 1,
    "eventsCount": 12,
    "createdAt": "2023-08-20T10:00:00",
    "isOwnProfile": false,
    "relationship": {
      "isFollowing": true,
      "isFollowedBy": false,
      "isBlocked": false,
      "isBlockedBy": false
    }
  }
}
```

**Success Response JSON Sample (Viewing Own Profile by ID)**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Profile retrieved successfully",
  "action_time": "2025-12-29T17:00:00",
  "data": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "userName": "john_doe",
    "firstName": "John",
    "lastName": "Doe",
    "profilePictureUrl": "https://storage.example.com/profiles/john.jpg",
    "bio": "Tech enthusiast | Entrepreneur | Dar es Salaam",
    "location": "Dar es Salaam, Tanzania",
    "isVerified": true,
    "followersCount": 1250,
    "followingCount": 340,
    "postsCount": 85,
    "shopsCount": 2,
    "eventsCount": 5,
    "createdAt": "2024-03-15T08:00:00",
    "isOwnProfile": true,
    "relationship": null
  }
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| userId | Unique identifier of the user |
| userName | Username handle |
| firstName | User's first name |
| lastName | User's last name |
| profilePictureUrl | URL to profile picture |
| bio | User's bio/description |
| location | User's location |
| isVerified | Whether user is verified |
| followersCount | Number of followers |
| followingCount | Number of users following |
| postsCount | Number of published posts |
| shopsCount | Number of active shops owned |
| eventsCount | Number of published events created |
| createdAt | Account creation date |
| isOwnProfile | `true` if viewing own profile, `false` otherwise |
| relationship | Relationship info (null if `isOwnProfile` is true) |

**Relationship Object Fields**:
| Field | Description |
|-------|-------------|
| isFollowing | Whether viewer follows this user |
| isFollowedBy | Whether this user follows viewer |
| isBlocked | Whether viewer has blocked this user |
| isBlockedBy | Whether this user has blocked viewer |

**Error Response JSON Sample**:
```json
{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "User not found",
  "action_time": "2025-12-29T17:00:00",
  "data": null
}
```

**Standard Error Types**:
- `400 BAD_REQUEST`: User not found
- `401 UNAUTHORIZED`: Missing or invalid authentication token

---

## 13. Get User Profile by Username

**Purpose**: Retrieve a user's profile summary by their username

**Endpoint**: <span style="background-color: #61affe; color: white; padding: 4px 8px; border-radius: 4px; font-family: monospace; font-size: 12px; font-weight: bold;">GET</span> `{base_url}/api/v1/profile/u/{username}`

**Access Level**: 🔒 Protected (Requires Authentication)

**Authentication**: Bearer Token

**Request Headers**:
| Header | Type | Required | Description |
|--------|------|----------|-------------|
| Authorization | string | Yes | Bearer token for authentication |

**Path Parameters**:
| Parameter | Type | Required | Description | Validation |
|-----------|------|----------|-------------|------------|
| username | string | Yes | Username of the user | Valid username format |

**Success Response JSON Sample (Viewing Other User)**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Profile retrieved successfully",
  "action_time": "2025-12-29T17:00:00",
  "data": {
    "userId": "660e8400-e29b-41d4-a716-446655440001",
    "userName": "jane_smith",
    "firstName": "Jane",
    "lastName": "Smith",
    "profilePictureUrl": "https://storage.example.com/profiles/jane.jpg",
    "bio": "Fashion designer | Shop owner | Arusha",
    "location": "Arusha, Tanzania",
    "isVerified": true,
    "followersCount": 5420,
    "followingCount": 180,
    "postsCount": 320,
    "shopsCount": 1,
    "eventsCount": 12,
    "createdAt": "2023-08-20T10:00:00",
    "isOwnProfile": false,
    "relationship": {
      "isFollowing": true,
      "isFollowedBy": true,
      "isBlocked": false,
      "isBlockedBy": false
    }
  }
}
```

**Success Response JSON Sample (Viewing Own Profile by Username)**:
```json
{
  "success": true,
  "httpStatus": "OK",
  "message": "Profile retrieved successfully",
  "action_time": "2025-12-29T17:00:00",
  "data": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "userName": "john_doe",
    "firstName": "John",
    "lastName": "Doe",
    "profilePictureUrl": "https://storage.example.com/profiles/john.jpg",
    "bio": "Tech enthusiast | Entrepreneur | Dar es Salaam",
    "location": "Dar es Salaam, Tanzania",
    "isVerified": true,
    "followersCount": 1250,
    "followingCount": 340,
    "postsCount": 85,
    "shopsCount": 2,
    "eventsCount": 5,
    "createdAt": "2024-03-15T08:00:00",
    "isOwnProfile": true,
    "relationship": null
  }
}
```

**Success Response Fields**:
| Field | Description |
|-------|-------------|
| userId | Unique identifier of the user |
| userName | Username handle |
| firstName | User's first name |
| lastName | User's last name |
| profilePictureUrl | URL to profile picture |
| bio | User's bio/description |
| location | User's location |
| isVerified | Whether user is verified |
| followersCount | Number of followers |
| followingCount | Number of users following |
| postsCount | Number of published posts |
| shopsCount | Number of active shops owned |
| eventsCount | Number of published events created |
| createdAt | Account creation date |
| isOwnProfile | `true` if viewing own profile, `false` otherwise |
| relationship | Relationship info (null if `isOwnProfile` is true) |

**Relationship Object Fields**:
| Field | Description |
|-------|-------------|
| isFollowing | Whether viewer follows this user |
| isFollowedBy | Whether this user follows viewer |
| isBlocked | Whether viewer has blocked this user |
| isBlockedBy | Whether this user has blocked viewer |

**Error Response JSON Sample**:
```json
{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "User not found",
  "action_time": "2025-12-29T17:00:00",
  "data": null
}
```

**Standard Error Types**:
- `400 BAD_REQUEST`: User not found
- `401 UNAUTHORIZED`: Missing or invalid authentication token

---

## Profile Endpoints Summary

| Endpoint | Purpose | `isOwnProfile` | `relationship` |
|----------|---------|----------------|----------------|
| `GET /api/v1/profile/me` | Get my profile | Always `true` | Always `null` |
| `GET /api/v1/profile/id/{userId}` | Get profile by ID | `true` if own ID | `null` if own profile |
| `GET /api/v1/profile/u/{username}` | Get profile by username | `true` if own username | `null` if own profile |

## Relationship Field Logic

| Scenario | `isOwnProfile` | `relationship` |
|----------|----------------|----------------|
| Viewing own profile via `/me` | `true` | `null` |
| Viewing own profile via `/id/{myId}` | `true` | `null` |
| Viewing own profile via `/u/{myUsername}` | `true` | `null` |
| Viewing other user's profile | `false` | `{ isFollowing, isFollowedBy, isBlocked, isBlockedBy }` |

## Frontend Usage Example

```javascript
const profile = response.data;

if (profile.isOwnProfile) {
    // Show edit profile button
    // Hide follow/block buttons
    showEditProfileButton();
} else {
    // Show follow button based on relationship
    if (profile.relationship.isFollowing) {
        showUnfollowButton();
    } else {
        showFollowButton();
    }
    
    // Show "Follows you" badge
    if (profile.relationship.isFollowedBy) {
        showFollowsYouBadge();
    }
    
    // Handle blocked state
    if (profile.relationship.isBlockedBy) {
        showLimitedProfile();
        disableInteractions();
    }
}
```

## Quick Reference Guide

### Security Strength Scoring
- **Email Verification**: 25 points
- **Phone Verification**: 25 points  
- **Two-Factor Authentication**: 35 points
- **Recent Password Change**: 15 points (within 6 months)

### Security Levels
- **STRONG (80-100)**: Excellent security
- **MEDIUM (60-79)**: Good security, can be improved
- **WEAK (40-59)**: Needs improvement
- **VERY_WEAK (0-39)**: Poor security, immediate attention needed

### Profile Picture Requirements
- **Format**: HTTPS URLs only
- **File Types**: JPG, JPEG, PNG, GIF, WebP
- **Limit**: Maximum 5 profile pictures
- **Size**: No specific limit (handled by file service)
- **Security**: SSRF protection implemented

### Common HTTP Status Codes
- `200 OK`: Successful GET/PUT request
- `204 No Content`: Successful DELETE request
- `400 Bad Request`: Invalid request data
- `401 Unauthorized`: Authentication required/failed
- `403 Forbidden`: Insufficient permissions
- `404 Not Found`: Resource not found
- `409 Conflict`: Username/email already taken
- `422 Unprocessable Entity`: Validation errors
- `429 Too Many Requests`: Rate limit exceeded
- `500 Internal Server Error`: Server error

### Authentication Types
- **Bearer Token**: Include `Authorization: Bearer your_access_token` in headers
- **Password Verification**: Required for sensitive operations (password change, 2FA, deactivation)
- **OTP Verification**: Required for email/phone verification
- **Re-authentication**: Required after username changes

### Data Format Standards
- **Dates**: Use ISO 8601 format (2025-09-23T10:30:00Z)
- **Phone Numbers**: E.164 international format (+1234567890)
- **UUIDs**: Standard UUID format for all identifiers
- **URLs**: Full HTTPS URLs for profile pictures
- **Passwords**: Min 8 chars, uppercase, lowercase, digit, special character