Password Management Guide

1. Password Expiry Process

The system enforces password rotation policies. When a user's password expires, the login process will signal the client to perform a mandatory password update.

Detection

When calling the /login endpoint, the JSON response includes a password_expired boolean flag.

{
    "access_token": "...",
    "password_expired": true,
    "first_time_login": false,
    ...
}

Implementation

The client application should immediately redirect the user to a "Change Password" screen and call the following endpoint:

Request Headers

• Authorization: Bearer {access_token}
• Content-Type: application/json

Request Body

{
    "old_password": "current_expired_password",
    "new_password": "new_secure_password"
}

Response Codes

2. Forgot Password Process

The "Forgot Password" workflow is a two-step process involving identity verification via a One-Time Password (OTP) sent to the user's registered email or phone.

Step 1: Request Password Reset

Initiate the reset process by providing the username and a verification channel.

Request Body

{
    "username": "john_doe",
    "email": "john@example.com",
    "phone": "+6512345678"
}

Provide either email or phone. The system will verify if the provided contact matches the records for that username.

Response

{
    "reset_token": "a1b2c3d4..."
}

The user will receive an OTP via the chosen channel. The reset_token returned in the response must be persisted by the client for the next step.

Step 2: Verify OTP and Update Password

Complete the reset by submitting the OTP, the token from Step 1, and the new password. You will need a UI screen for this.

Request Body

{
    "reset_token": "a1b2c3d4...",
    "otp": "123456",
    "new_password": "new_secure_password",
    "reset_totp": false
}

Parameters