Profile Management Service

⚠️ CRITICAL REQUIREMENTS

🔐 Authentication Required

ALL endpoints in this service require Bearer token authentication. No exceptions. Requests without valid authentication will receive a 401 Unauthorized response.

🚨 Username Change Token Invalidation

CRITICAL: When updating a username via /update-basic-info, the user's current access token becomes invalid immediately after the change. The frontend MUST:

Redirect to login page after successful username change
Clear all stored tokens (access token, refresh token)
Force re-authentication with the new username
Display appropriate message informing user of required re-login

🖼️ Profile Picture URL Restriction

IMPORTANT: The profilePictureUrls field ONLY accepts URLs generated from our File Upload Service endpoint (/api/v1/files/upload). External URLs or direct links are NOT permitted for security reasons.

Valid URL Format: http://localhost:9005/{bucket-name}/{object-key} Source: Must be uploaded through /api/v1/files/upload with directory=PROFILE

Service Overview

The Profile Management Service provides comprehensive user profile management capabilities including profile updates, security settings, verification, and account management.

Base URL

/api/v1/profile

Endpoints Overview

Method

Endpoint

Description

GET

/me

Get current user profile

PUT

/update-basic-info

Update basic profile information

PUT

/change-password

Change user password

GET

/validate-username/{username}

Validate username availability

POST

/request-email-verification

Request email verification

POST

/verify-email

Verify email with OTP

GET

/security-info

Get security information

POST

/enable-2fa

Enable two-factor authentication

POST

/disable-2fa

Disable two-factor authentication

DELETE

/deactivate

Deactivate user account

Get Current User Profile

Retrieves the complete profile information for the authenticated user.

Request

GET /api/v1/profile/me
Authorization: Bearer {access_token}

Response

{
  "success": true,
  "httpStatus": "OK",
  "message": "Profile retrieved successfully",
  "action_time": "2024-12-09T10:30:00",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userName": "john-doe123",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Smith",
    "email": "john.doe@example.com",
    "phoneNumber": "+1234567890",
    "isVerified": true,
    "isEmailVerified": true,
    "isPhoneVerified": false,
    "isTwoFactorEnabled": false,
    "isAccountLocked": false,
    "createdAt": "2024-01-15T09:30:00",
    "editedAt": "2024-12-09T10:15:00",
    "roles": ["ROLE_NORMAL_USER"],
    "profilePictureUrls": [
      "http://localhost:9005/org-123e4567-e89b-12d3-a456-426614174000/profile/image1.jpg",
      "http://localhost:9005/org-123e4567-e89b-12d3-a456-426614174000/profile/image2.jpg"
    ],
    "securityStrength": {
      "score": 85,
      "level": "STRONG",
      "description": "Your account security is excellent",
      "recommendations": []
    }
  }
}

Error Responses

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Invalid token",
  "action_time": "2024-12-09T10:30:00"
}

{
  "success": false,
  "httpStatus": "NOT_FOUND",
  "message": "User not found",
  "action_time": "2024-12-09T10:30:00"
}

Update Basic Profile Information

Updates basic user profile information including name, email, username, and profile pictures.

Request

PUT /api/v1/profile/update-basic-info
Authorization: Bearer {access_token}
Content-Type: application/json

Request Body

{
  "userName": "john-doe123",
  "firstName": "John",
  "lastName": "Doe", 
  "middleName": "Smith",
  "email": "john.doe@example.com",
  "phoneNumber": "+1234567890",
  "profilePictureUrls": [
    "http://localhost:9005/org-123e4567-e89b-12d3-a456-426614174000/profile/image1.jpg",
    "http://localhost:9005/org-123e4567-e89b-12d3-a456-426614174000/profile/image2.jpg"
  ]
}

Field Validation

userName: 3-30 characters, must start with letter, alphanumeric + underscore/hyphen only
firstName: 1-30 characters, required
lastName: 1-30 characters, required
middleName: Max 30 characters, optional
email: Valid email format
phoneNumber: International format (+1234567890)
profilePictureUrls:
- Max 5 URLs
- Each URL max 500 characters
- MUST be URLs from File Upload Service only (/api/v1/files/upload-single with directory=PROFILE)
- External URLs are rejected for security reasons

Response (Normal Update)

{
  "success": true,
  "httpStatus": "OK", 
  "message": "Profile updated successfully",
  "action_time": "2024-12-09T10:30:00",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userName": "john-doe123",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Smith",
    "email": "john.doe@example.com",
    "phoneNumber": "+1234567890",
    "isVerified": true,
    "isEmailVerified": false,
    "isPhoneVerified": false,
    "isTwoFactorEnabled": false,
    "isAccountLocked": false,
    "createdAt": "2024-01-15T09:30:00",
    "editedAt": "2024-12-09T10:30:00",
    "roles": ["ROLE_NORMAL_USER"],
    "profilePictureUrls": [
      "http://localhost:9005/org-123e4567-e89b-12d3-a456-426614174000/profile/image1.jpg",
      "http://localhost:9005/org-123e4567-e89b-12d3-a456-426614174000/profile/image2.jpg"
    ],
    "securityStrength": {
      "score": 75,
      "level": "STRONG",
      "description": "Your account security is excellent",
      "recommendations": ["Verify your email address"]
    }
  }
}

⚠️ CRITICAL: Username Change Response

When the username is updated, the response includes a special message and the frontend MUST handle token invalidation:

{
  "success": true,
  "httpStatus": "OK",
  "message": "Username changed successfully! You will be logged out automatically. Please login again with your new username.",
  "action_time": "2024-12-09T10:30:00",
  "data": { /* updated profile data */ }
}

IMMEDIATE ACTION REQUIRED:

Clear all stored tokens (access token, refresh token)
Redirect user to login page
Display the message to inform user of required re-authentication
User must login again with their NEW username

Error Responses

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Username is already taken",
  "action_time": "2024-12-09T10:30:00"
}

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Invalid profile picture URL. Only URLs from File Upload Service are allowed.",
  "action_time": "2024-12-09T10:30:00"
}

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2024-12-09T10:30:00",
  "data": {
    "userName": "Username must be between 3 and 30 characters",
    "email": "Email should be valid",
    "profilePictureUrls": "Only URLs from File Upload Service are allowed"
  }
}

Change Password

Changes the user's password with current password verification.

Request

PUT /api/v1/profile/change-password
Authorization: Bearer {access_token}
Content-Type: application/json

Request Body

{
  "currentPassword": "oldPassword123!",
  "newPassword": "newPassword456@",
  "confirmPassword": "newPassword456@"
}

Password Requirements

Minimum 8 characters
At least one uppercase letter
At least one lowercase letter
At least one digit
At least one special character (@$!%*?&#)
Must be different from current password

Response

{
  "success": true,
  "httpStatus": "OK",
  "message": "Password changed successfully",
  "action_time": "2024-12-09T10:30:00"
}

Error Responses

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Current password is incorrect",
  "action_time": "2024-12-09T10:30:00"
}

{
  "success": false,
  "httpStatus": "BAD_REQUEST", 
  "message": "New password must be different from current password",
  "action_time": "2024-12-09T10:30:00"
}

Validate Username

Checks username availability and format validity with suggestions.

Request

GET /api/v1/profile/validate-username/{username}
Authorization: Bearer {access_token}

Response (Available)

{
  "success": true,
  "httpStatus": "OK",
  "message": "Username validation completed",
  "action_time": "2024-12-09T10:30:00",
  "data": {
    "available": true,
    "valid": true,
    "message": "Username is available",
    "suggestions": [],
    "details": {
      "correctLength": true,
      "validFormat": true,
      "notReserved": true,
      "notTaken": true,
      "formatRequirement": "Username must start with a letter and be 3-30 characters long"
    }
  }
}

Response (Not Available)

{
  "success": true,
  "httpStatus": "OK",
  "message": "Username validation completed", 
  "action_time": "2024-12-09T10:30:00",
  "data": {
    "available": false,
    "valid": true,
    "message": "This username is already taken",
    "suggestions": [
      "johndoe1",
      "johndoe2", 
      "johndoeuser",
      "johndoepro",
      "johndoe5634"
    ],
    "details": {
      "correctLength": true,
      "validFormat": true,
      "notReserved": true,
      "notTaken": false,
      "formatRequirement": "Username must start with a letter and be 3-30 characters long"
    }
  }
}

Request Email Verification

Sends an OTP to the user's email for verification.

Request

POST /api/v1/profile/request-email-verification
Authorization: Bearer {access_token}

Response

{
  "success": true,
  "httpStatus": "OK",
  "message": "Email verification OTP sent successfully",
  "action_time": "2024-12-09T10:30:00",
  "data": {
    "tempToken": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWRlbnRpZmllciI6Im...",
    "message": "Verification email sent successfully",
    "expireAt": "2024-12-09T10:40:00",
    "email": "jo***@example.com"
  }
}

Error Responses

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Email is already verified",
  "action_time": "2024-12-09T10:30:00"
}

Verify Email

Verifies email address using the OTP code sent via email.

Request

POST /api/v1/profile/verify-email
Authorization: Bearer {access_token}
Content-Type: application/json

Request Body

{
  "tempToken": "eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWRlbnRpZmllciI6Im...",
  "otpCode": "123456"
}

Response

{
  "success": true,
  "httpStatus": "OK",
  "message": "Email verified successfully",
  "action_time": "2024-12-09T10:30:00",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userName": "john-doe123",
    "firstName": "John",
    "lastName": "Doe",
    "middleName": "Smith",
    "email": "john.doe@example.com",
    "phoneNumber": "+1234567890",
    "isVerified": true,
    "isEmailVerified": true,
    "isPhoneVerified": false,
    "isTwoFactorEnabled": false,
    "isAccountLocked": false,
    "createdAt": "2024-01-15T09:30:00",
    "editedAt": "2024-12-09T10:30:00",
    "roles": ["ROLE_NORMAL_USER"],
    "profilePictureUrls": [],
    "securityStrength": {
      "score": 85,
      "level": "STRONG", 
      "description": "Your account security is excellent",
      "recommendations": ["Verify your phone number"]
    }
  }
}

Error Responses

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Invalid OTP code",
  "action_time": "2024-12-09T10:30:00"
}

Get Security Information

Retrieves comprehensive security information and account strength analysis.

Request

GET /api/v1/profile/security-info
Authorization: Bearer {access_token}

Response

{
  "success": true,
  "httpStatus": "OK",
  "message": "Security information retrieved successfully",
  "action_time": "2024-12-09T10:30:00",
  "data": {
    "isEmailVerified": true,
    "isPhoneVerified": false,
    "isTwoFactorEnabled": false,
    "isAccountLocked": false,
    "lastPasswordChange": "2024-12-09T10:15:00",
    "accountCreatedAt": "2024-01-15T09:30:00",
    "roles": ["ROLE_NORMAL_USER"],
    "securityStrength": {
      "score": 75,
      "level": "STRONG",
      "description": "Your account security is good but can be improved",
      "recommendations": [
        "Verify your phone number",
        "Enable two-factor authentication"
      ]
    }
  }
}

Security Strength Scoring

Email Verification: 25 points
Phone Verification: 25 points
Two-Factor Authentication: 35 points
Recent Password Change (last 6 months): 15 points

Security Levels

80-100: STRONG - "Your account security is excellent"
60-79: MEDIUM - "Your account security is good but can be improved"
40-59: WEAK - "Your account security needs improvement"
0-39: VERY_WEAK - "Your account security is poor and needs immediate attention"

Enable Two-Factor Authentication

Enables two-factor authentication for the user account.

Request

POST /api/v1/profile/enable-2fa
Authorization: Bearer {access_token}
Content-Type: application/json

Request Body

{
  "password": "userPassword123!"
}

Response

{
  "success": true,
  "httpStatus": "OK",
  "message": "Two-factor authentication enabled successfully",
  "action_time": "2024-12-09T10:30:00"
}

Error Responses

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Password is incorrect",
  "action_time": "2024-12-09T10:30:00"
}

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Two-factor authentication is already enabled",
  "action_time": "2024-12-09T10:30:00"
}

Disable Two-Factor Authentication

Disables two-factor authentication for the user account.

Request

POST /api/v1/profile/disable-2fa
Authorization: Bearer {access_token}
Content-Type: application/json

Request Body

{
  "password": "userPassword123!"
}

Response

{
  "success": true,
  "httpStatus": "OK",
  "message": "Two-factor authentication disabled successfully",
  "action_time": "2024-12-09T10:30:00"
}

Error Responses

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Password is incorrect",
  "action_time": "2024-12-09T10:30:00"
}

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Two-factor authentication is not enabled",
  "action_time": "2024-12-09T10:30:00"
}

Deactivate Account

Deactivates (soft deletes) the user account by locking it.

Request

DELETE /api/v1/profile/deactivate
Authorization: Bearer {access_token}
Content-Type: application/json

Request Body

{
  "password": "userPassword123!",
  "reason": "No longer need the account"
}

Response

{
  "success": true,
  "httpStatus": "OK",
  "message": "Account deactivated successfully",
  "action_time": "2024-12-09T10:30:00"
}

Error Responses

{
  "success": false,
  "httpStatus": "FORBIDDEN",
  "message": "Password is incorrect",
  "action_time": "2024-12-09T10:30:00"
}

Common Error Responses

Authentication Errors

ALL endpoints require valid Bearer token authentication:

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Invalid token",
  "action_time": "2024-12-09T10:30:00"
}

{
  "success": false,
  "httpStatus": "UNAUTHORIZED", 
  "message": "Token expired",
  "action_time": "2024-12-09T10:30:00"
}

{
  "success": false,
  "httpStatus": "UNAUTHORIZED",
  "message": "Authorization header missing",
  "action_time": "2024-12-09T10:30:00"
}

Validation Errors

{
  "success": false,
  "httpStatus": "UNPROCESSABLE_ENTITY",
  "message": "Validation failed",
  "action_time": "2024-12-09T10:30:00",
  "data": {
    "fieldName": "Error message for specific field"
  }
}

Rate Limiting Errors

{
  "success": false,
  "httpStatus": "BAD_REQUEST",
  "message": "Too many requests. Please wait before requesting again.",
  "action_time": "2024-12-09T10:30:00"
}

Security Features

Password Strength Analysis

The system analyzes password strength based on:

Length (minimum 8 characters)
Character diversity (uppercase, lowercase, numbers, special characters)
Common password patterns

Rate Limiting

OTP requests: Limited to prevent abuse
Failed attempts: Tracked and limited
Cooldown periods: Applied between requests

Email Notifications

Password changes trigger security notifications
Account deactivation confirmations
Verification code deliveries

Data Validation

Input sanitization for XSS prevention
URL validation for profile pictures
Phone number format validation
Email format validation

Profile Picture Security

Maximum 5 URLs per user
URL length limits (500 characters)
ONLY accepts URLs from File Upload Service (/api/v1/files/upload-single)
Format validation (image extensions only)
External URL blocking for security (SSRF protection)
Valid URL pattern: http://localhost:9005/{bucket-name}/{object-key}

Best Practices for Frontend Integration

⚠️ Critical Authentication Handling

Token Validation: Always check token validity before making requests
Token Storage: Store access tokens securely
Username Change Flow:
- Detect username change response message
- Immediately clear all stored authentication data
- Redirect to login page with appropriate message
- Force user to re-authenticate with new username
Token Refresh: Implement proper token refresh mechanisms
Error Handling: Handle 401 errors by redirecting to login

Security Considerations

Password Handling: Never log or persist passwords
Form Validation: Implement client-side validation matching server rules
Error Messages: Display user-friendly error messages without exposing sensitive information
Loading States: Show appropriate loading indicators for async operations
Session Management: Clear all user data on authentication failures

Username Change Implementation Requirements

When handling username update responses, the frontend must:

Check Response Message: Look for the specific message "Username changed successfully! You will be logged out automatically..."
Clear Authentication Data: Remove all stored tokens and user session data
User Notification: Display the response message to inform user of required re-authentication
Force Re-login: Redirect user to login page immediately
Block Further API Calls: Prevent any additional authenticated requests until re-login

User Experience

Progressive Disclosure: Show security strength indicators
Real-time Validation: Validate usernames and emails as user types
Clear Feedback: Provide immediate feedback for actions
Confirmation Dialogs: Confirm destructive actions like account deactivation
Auto-logout: Handle username changes by logging user out

Performance

Debounced Validation: Debounce username validation requests
Caching: Cache profile data appropriately
Optimistic Updates: Update UI optimistically where safe
Error Recovery: Implement retry mechanisms for failed requests

Profile Picture Handling

File Upload First: Always upload images via File Upload Service before updating profile
URL Validation: Only use URLs returned from /api/v1/files/upload-single
Error Handling: Handle profile picture URL validation errors appropriately
Preview: Show image previews before updating profile

PreviousFile Management Service NextShops Management Service

Last updated 5 months ago

Good morning

hashtag⚠️ CRITICAL REQUIREMENTS

hashtag🔐 Authentication Required

hashtag🚨 Username Change Token Invalidation

hashtag🖼️ Profile Picture URL Restriction

hashtagService Overview

hashtagBase URL

hashtagEndpoints Overview

hashtagGet Current User Profile

hashtagRequest

hashtagResponse

hashtagError Responses

hashtagUpdate Basic Profile Information

hashtagRequest

hashtagRequest Body

hashtagField Validation

hashtagResponse (Normal Update)

hashtag⚠️ CRITICAL: Username Change Response

hashtagError Responses

hashtagChange Password

hashtagRequest

hashtagRequest Body

hashtagPassword Requirements

hashtagResponse

hashtagError Responses

hashtagValidate Username

hashtagRequest

hashtagResponse (Available)

hashtagResponse (Not Available)

hashtagRequest Email Verification

hashtagRequest

hashtagResponse

hashtagError Responses

hashtagVerify Email

hashtagRequest

hashtagRequest Body

hashtagResponse

hashtagError Responses

hashtagGet Security Information

hashtagRequest

hashtagResponse

hashtagSecurity Strength Scoring

hashtagSecurity Levels

hashtagEnable Two-Factor Authentication

hashtagRequest

hashtagRequest Body

hashtagResponse

hashtagError Responses

hashtagDisable Two-Factor Authentication

hashtagRequest

hashtagRequest Body

hashtagResponse

hashtagError Responses

hashtagDeactivate Account

hashtagRequest

hashtagRequest Body

hashtagResponse

hashtagError Responses

hashtagCommon Error Responses

hashtagAuthentication Errors

hashtagValidation Errors

hashtagRate Limiting Errors

hashtagSecurity Features

hashtagPassword Strength Analysis

hashtagRate Limiting

hashtagEmail Notifications

hashtagData Validation

hashtagProfile Picture Security

hashtagBest Practices for Frontend Integration

hashtag⚠️ Critical Authentication Handling

hashtagSecurity Considerations

hashtagUsername Change Implementation Requirements

hashtagUser Experience

hashtagPerformance

hashtagProfile Picture Handling

⚠️ CRITICAL REQUIREMENTS

🔐 Authentication Required

🚨 Username Change Token Invalidation

🖼️ Profile Picture URL Restriction

Service Overview

Base URL

Endpoints Overview

Get Current User Profile

Request

Response

Error Responses

Update Basic Profile Information

Request

Request Body

Field Validation

Response (Normal Update)

⚠️ CRITICAL: Username Change Response

Error Responses

Change Password

Request

Request Body

Password Requirements

Response

Error Responses

Validate Username

Request

Response (Available)

Response (Not Available)

Request Email Verification

Request

Response

Error Responses

Verify Email

Request

Request Body

Response

Error Responses

Get Security Information

Request

Response

Security Strength Scoring

Security Levels

Enable Two-Factor Authentication

Request

Request Body

Response

Error Responses

Disable Two-Factor Authentication

Request

Request Body

Response

Error Responses

Deactivate Account

Request

Request Body

Response

Error Responses

Common Error Responses

Authentication Errors

Validation Errors

Rate Limiting Errors

Security Features

Password Strength Analysis

Rate Limiting

Email Notifications

Data Validation

Profile Picture Security

Best Practices for Frontend Integration

⚠️ Critical Authentication Handling

Security Considerations

Username Change Implementation Requirements

User Experience

Performance

Profile Picture Handling