Account Recovery with OTP Verification

Send Unlock OTP

The Send Unlock OTP endpoint initiates the account recovery process for locked user accounts. It generates a time-bound One-Time Password and delivers it to the user's registered contact method (mobile number or email address). This endpoint supports a two-step flow: first request the OTP using only the user's nickname, then validate it by submitting both the nickname and the received code.

Endpoint

POST /api/auth/SendUnlockOtp

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when a user's account has been locked and they need to regain access. The endpoint supports multi-factor authentication (MFA) flows where a secondary verification step is required before unlocking. Call it first with only the nickName to trigger OTP dispatch, then call it again with both nickName and code to complete validation and unlock the account.

Request Body

This endpoint accepts one of two request schemas depending on the step in the unlock flow.

Step 1 — Request OTP (lockoutrequest): Submit the user's nickname to trigger OTP delivery.

{
  "nickName": "john.doe"
}

Step 2 — Validate OTP (lockoutvalidationrequest): Submit the nickname along with the OTP code received by the user.

{
  "nickName": "john.doe",
  "code": "847291"
}

Response

200 OK

A successful response confirms that the OTP has been sent to the user's registered contact details (Step 1), or that the OTP has been validated and the account unlock process has been completed (Step 2). The response body on success is empty or returns a confirmation message.

{}

Error Codes

Common Mistakes

• Submitting the code field in Step 1 (OTP request) — only nickName is needed at that stage.
• Omitting nickName in Step 2 (OTP validation) — both nickName and code are required together.
• Using an expired OTP — the code is time-bound and must be submitted within the validity window.
• Passing an empty string for nickName or code — both fields enforce a minimum length of 1 character.

Related Endpoints

• POST /api/auth/v2 — Obtain a Bearer authentication token
• 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/api/auth/SendUnlockOtp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nickName": "john.doe"
  }'

Step 2 — Validate OTP:

curl -X POST https://api.banking.netevia.dev/api/auth/SendUnlockOtp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nickName": "john.doe",
    "code": "847291"
  }'