Verification Management

Verification Start Point

Frontend should also be aware of verification after any login attempt. The login request may return a 401 or 403 with the error codes that indicates the verification needs.

{
  //...
  "errCode": "EmailVerificationNeeded",
  // or
  "errCode": "MobileVerificationNeeded"
}

Email Verification

In the registration response, check the emailVerificationNeeded property in the response root. If it is true, start the email verification flow.

After the login process, if you receive an HTTP error and the response contains an errCode with the value EmailVerificationNeeded, start the email verification flow.

1. Call the email verification start route of the backend (described below) with the user’s email. The backend will send a secret code to the provided email address. The backend can send the email if the architect has configured a real mail service or SMTP server. During development, the backend also returns the secret code to the frontend. You can read this code from the******secretCode************** property of the response.

2. The secret code in the email will be a 6-digit code. Provide an input page so the user can paste this code into the frontend application. Navigate to this input page after starting the verification process. If the******secretCode************** is sent to the frontend for testing, display it on the input page so the user can copy and paste it.

3. The start response includes a codeIndex property. Display its value on the input page so the user can match the index in the message with the one on the screen.

4. When the user submits the code, complete the email verification using the complete route of the backend (described below) with the user’s email and the secret code.

5. After a successful email verification response, please check the response object to have the property 'mobileVerificationNeeded' as true, if so navigate to the mobile verification flow as described below. If no mobile verification is needed then just navigate the login page.

Below are the start and complete routes for email verification. These are system routes and therefore are not versioned.

POST /verification-services/email-verification/start

Purpose: Starts email verification by generating and sending a secret code.

Example Request

{ "email": "user@example.com" }

Success Response

{
  "status": "OK",
  "codeIndex": 1,
  // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT
  "timeStamp": 1784578660000,
  "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)",
  // expireTime: in seconds
  "expireTime": 86400,
  "verificationType": "byLink",

  // in testMode
  "secretCode": "123456",
  "userId": "user-uuid"
}

Error Responses

• 400 Bad Request: Already verified

• 403 Forbidden: Too many attempts (rate limit)

POST /verification-services/email-verification/complete

Purpose: Completes verification using the received code.

Success Response

{
  "status": "OK",
  "isVerified": true,
  "email": "user@email.com",
  // in testMode
  "userId": "user-uuid"
}

Error Responses

• 403 Forbidden: Code expired or mismatched

• 404 Not Found: No verification in progress

Mobile Verification

In the registration response, check the mobileVerificationNeeded property in the response root. If it is true, start the mobile verification flow.

After the login process, if you receive a 403 error and the response contains an errCode with the value MobileVerificationNeeded, start the mobile verification flow.

1. Call the mobile verification start route of the backend (described below) with the user’s email. The backend will send a secret code to the user’s mobile number. If a real texting service is configured, the backend sends the SMS. During development, the backend also returns the secret code to the frontend in the******secretCode************** property.

2. The secret code in the SMS will be a 6-digit code. Provide an input page so the user can paste this code. Navigate to this input page after starting the verification process. If the******secretCode************** is returned for testing, display it on the input page for easy copy/paste.

3. When the user submits the code, complete mobile verification using the complete route of the backend (described below) with the user’s email and the secret code.

4. The start response includes a codeIndex property. Display its value on the input page so the user can match the index shown in the message with the one on the screen.

5. After a successful mobile verification response, navigate to the login page.

Verification Order If both emailVerificationNeeded and mobileVerificationNeeded are true, handle both verification flows in order. First complete email verification, then mobile verification.

Below are the start and complete routes for mobile verification. These are system routes and therefore are not versioned.

POST /verification-services/mobile-verification/start

Success Response

{
  "status": "OK",
  "codeIndex": 1,
  // timeStamp : Milliseconds since Jan 1, 1970, 00:00:00.000 GMT
  "timeStamp": 1784578660000,
  "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)",
  // expireTime: in seconds
  "expireTime": 180,
  "verificationType": "byCode",

  // in testMode
  "secretCode": "123456",
  "userId": "user-uuid"
}

Errors

• 400 Bad Request: Already verified

• 403 Forbidden: Rate-limited

POST /verification-services/mobile-verification/complete

Success Response

{
  "status": "OK",
  "isVerified": true,
  "mobile": "+1 333 ...",
  // in testMode
  "userId": "user-uuid"
}

Resetting Password

Users can reset their forgotten passwords without a login required, through email and mobile verification. To be able to start a password reset flow, users will click on the "Reset Password" link in the login page.

Since there are two verification methods, by email or by mobile, for password reset, when the reset password link is clicked, frontend should ask user if they want to make the verification through email of mobile. According to the users selection the frontend shoudl start the related flow as explaned below step by step.

Password Reset By Email Flow

1. Call the password reset by email verification start route of the backend (described below) with the user’s email. The backend will send a secret code to the provided email address. The backend can send the email if the architect has configured a real mail service or SMTP server. During development, the backend also returns the secret code to the frontend. You can read this code from the******secretCode************** property of the response.

2. The secret code in the email will be a 6-digit code. Provide an input page so the user can paste this code into the frontend application. Navigate to this input page after starting the verification process. If the******secretCode************** is sent to the frontend for testing, display it on the input page so the user can copy and paste it.

3. The start response includes a codeIndex property. Display its value on the input page so the user can match the index in the message with the one on the screen.

4. The input page should also include a double input area for the user to enter and confirm their new password.

5. When the user submits the code and the new password, complete the password reset by email using the complete route of the backend (described below) with the user’s email , the secret code and new password.

6. After a successful verification response, navigate to the login page.

Below are the start and complete routes for password reset by email verification. These are system routes and therefore are not versioned.

POST /verification-services/password-reset-by-email/start

Purpose:
Starts the password reset process by generating and sending a secret verification code.

Request Body

{
  "email": "user@example.com"
}

Success Response

Returns secret code details (only in development environment) and confirmation that the verification step has been started.

{
  "userId": "user-uuid",
  "email": "user@example.com",
  "codeIndex": 1,
  "secretCode": "123456",
  "timeStamp": 1765484354,
  "expireTime": 86400,
  "date": "2024-04-29T10:00:00.000Z",
  "verificationType": "byLink"
}

⚠️ In production, the secret code is only sent via email and not exposed in the API response.

Error Responses

• 401 NotAuthenticated: Email address not found or not associated with a user.

• 403 Forbidden: Sending a code too frequently (spam prevention).

POST /verification-services/password-reset-by-email/complete

Purpose:
Completes the password reset process by validating the secret code and updating the user's password.

Request Body

{
  "email": "user@example.com",
  "secretCode": "123456",
  "password": "newSecurePassword123"
}

Success Response

{
  "userId": "user-uuid",
  "email": "user@example.com",
  "isVerified": true
}

Error Responses

• 403 Forbidden:

  • Secret code mismatch

  • Secret code expired

  • No ongoing verification found

Password Reset By Mobile Flow

1. Call the password reset by mobile verification start route of the backend (described below) with the user’s email. The backend will send a secret code to the user’s mobile number. If a real texting service is configured, the backend sends the SMS. During development, the backend also returns the secret code to the frontend in the******secretCode************** property.

2. The secret code in the SMS will be a 6-digit code. Provide an input page so the user can paste this code. Navigate to this input page after starting the verification process. If the******secretCode************** is returned for testing, display it on the input page for easy copy/paste.

3. The start response includes a codeIndex property. Display its value on the input page so the user can match the index in the message with the one on the screen. Also display the half masked mobilenumber that comes in the response, to tell the user that their code is sent to this number.

4. The input page should also include a double input area for the user to enter and confirm their new password.

5. When the user submits the code, complete mobile verification using the complete route of the backend (described below) with the user’s email and the secret code.

6. After a successful mobile verification response, navigate to the login page.

Below are the start and complete routes for password reset by mobile verification. These are system routes and therefore are not versioned.

POST /verification-services/password-reset-by-mobile/start

Purpose:
Initiates the mobile-based password reset by sending a verification code to the user's mobile.

Request Body

{
  "email": "user@user.com"
}

Success Response

Returns the verification context (code returned only in development):

{
  "status": "OK",
  "codeIndex": 1,
  "timeStamp": 133241255,
  "mobile": "+905.....67",
  "secretCode": "123456",
  "expireTime": 86400,
  "date": "2024-04-29T10:00:00.000Z",
  "verificationType": "byLink"
}

⚠️ In production, the secretCode is not included in the response and is only sent via SMS.

Error Responses

• 400 Bad Request: Mobile already verified

• 403 Forbidden: Rate-limited (code already sent recently)

• 404 Not Found: User with provided mobile not found

POST /verification-services/password-reset-by-mobile/complete

Purpose:
Finalizes the password reset process by validating the received verification code and updating the user’s password.

Request Body

{
  "email": "user@example.com",
  "secretCode": "123456",
  "password": "NewSecurePassword123!"
}

Success Response

{
  "userId": "user-uuid",
  "isVerified": true
}

Navigating to the Login Page

Please note that since this application is multitenant, the login page that will be navigated to after a verification process, should be aware of the tenant store. If this login navigate is after a user registration (or after a post-registration verification) to a store, then keep the active store as the original and navigate user to the selected store. If this login navigate is after a store registration (or after a tenant post-registration verification), then you have a new store other than the root one, so you should make this new tenant as the selected one and navigate to its login page. If this login is after a post-login verification, then keep the original store that the previous login attempt is made to and navigate to the same store either it is the root or/and registered store.

** Please don't forget to arrange the code to be able to navigate to the verification pages both after registrations and login attempts if verification is needed.**