Reset a user password

Prerequisites

The user's login email (username)
Either the current password or a one-time password (OTP) obtained through the forgot-password flow

Password requirements

Rule	Constraint
Minimum length	12 characters
Maximum length	128 characters
Format	Use a strong passphrase or complex password

Option A: Change password (known current password)

Use this when the user knows their current password and wants to set a new one.

Step 1: Send the password update

Send PATCH /v1/users/me/passwords with Basic Auth (username + current password).

curl -X PATCH \
  https://api.dev.paradisegateway.net/v1/users/me/passwords \
  -u "john.doe@example.com:current-password-here" \
  -H "Content-Type: application/json" \
  -d '{
    "user_name": "john.doe@example.com",
    "current_password": "Meat-Said-Whispered-Plant6-One",
    "new_password": "Rocky-Change-Thread-Tank1-Slowly"
  }'

Response

A 200 response confirms the password was changed.

{
  "status": true,
  "correlation_id": "e5f6a7b8-c9d0-1234-ef01-23456789abcd"
}

Option B: Forgot password (OTP flow)

Use this when the user has forgotten their password. This is a two-step process.

Step 1: Request a one-time password

Send POST /v1/mfa/challenges with type: forgot_password and the user's email.

curl -X POST \
  https://api.dev.paradisegateway.net/v1/mfa/challenges \
  -H "Content-Type: application/json" \
  -d '{
    "user_name": "john.doe@example.com",
    "type": "forgot_password"
  }'

Response:

{
  "status": true,
  "correlation_id": "f6a7b8c9-d0e1-2345-f012-3456789abcde"
}

The user receives the OTP at their registered email address.

Step 2: Set new password with OTP

Send PATCH /v1/users/me/passwords with the one_time_password field instead of current_password.

curl -X PATCH \
  https://api.dev.paradisegateway.net/v1/users/me/passwords \
  -H "Content-Type: application/json" \
  -d '{
    "user_name": "john.doe@example.com",
    "one_time_password": "123456",
    "current_password": "placeholder",
    "new_password": "Hat-Chest-Clock5-Solid-Round"
  }'