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: GET 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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Shop Categories Management

Shop Management

Shop Rating

Shop Review

Product Management

Cart Management

Wishlist Management

Wallet

Transaction History

Installment Purchase - Customer Endpoints

Installment Purchase - Public & Plan Endpoints

Installment Plan Management - Admin/Shop Endpoints

User Profile Management Service

Endpoints

1. Get Current User Profile

2. Update Basic Profile Information

3. Change Password

4. Validate Username Availability

5. Request Email Verification

6. Verify Email

7. Get Security Information

8. Enable Two-Factor Authentication

9. Disable Two-Factor Authentication

10. Deactivate Account

Quick Reference Guide

Security Strength Scoring

Security Levels

Profile Picture Requirements

Common HTTP Status Codes

Authentication Types

Data Format Standards