Password Reset via OTP

This endpoint supports a two-step password reset flow. In the first step, a user submits their username (nickName) to trigger an OTP email. In the second step, the user submits the OTP code along with their new password to complete the reset. No authentication token is required for either step, enabling users to recover access without being logged in.

Endpoint

POST /v2/forgotPassword

Authentication

No authentication required. This endpoint is publicly accessible to support account recovery.

When to use

Use this endpoint when a user has forgotten their password and needs to regain access to their account. Call it first with only nickName to send the reset OTP, then call it again with nickName, code, password, and passwordConfirm to finalize the password change. This endpoint should be surfaced in login screens and account recovery flows.

Request Body

This endpoint accepts one of two request shapes depending on the step in the reset flow.

Step 1 — Request OTP (forgotpasswordrequest)

{
  "nickName": "john.doe"
}

Step 2 — Set New Password (restorepasswordrequest)

This shape extends Step 1 and includes all fields from forgotpasswordrequest plus the fields below.

{
  "nickName": "john.doe",
  "code": "748291",
  "password": "NewSecureP@ssw0rd!",
  "passwordConfirm": "NewSecureP@ssw0rd!"
}

Response

200 OK

Step 1 — OTP sent successfully:

{
  "restoreState": "OtpSent",
  "errors": null,
  "success": "A password reset code has been sent to your registered email."
}

Step 2 — Password changed successfully:

{
  "restoreState": "PasswordChanged",
  "errors": null,
  "success": "Your password has been successfully updated."
}

Error response example:

{
  "restoreState": null,
  "errors": ["Username not found.", "Invalid or expired OTP code."],
  "success": null
}

Error Codes

Common Mistakes

• Submitting Step 2 fields (code, password, passwordConfirm) without also including nickName, which is required in both steps.
• Sending password and passwordConfirm with different values — they must match exactly.
• Reusing an OTP code that has already been used or has expired; request a new OTP by calling Step 1 again.
• Attempting to set a password that does not meet the platform's password complexity requirements, which will result in a 400 error with details in the errors array.

Related Endpoints

• POST /api/auth/v2 — Obtain a Bearer authentication token using username and password
• POST /api/auth/refresh — Refresh an existing Bearer token before it expires

Example

Step 1 — Request OTP:

curl -X POST https://api.banking.netevia.dev/v2/forgotPassword \
  -H "Content-Type: application/json" \
  -d '{
    "nickName": "john.doe"
  }'

Step 2 — Set New Password:

curl -X POST https://api.banking.netevia.dev/v2/forgotPassword \
  -H "Content-Type: application/json" \
  -d '{
    "nickName": "john.doe",
    "code": "748291",
    "password": "NewSecureP@ssw0rd!",
    "passwordConfirm": "NewSecureP@ssw0rd!"
  }'