WORKFORCEOS

FRONTEND GUIDE FOR AI CODING AGENTS - PART 3 - Verification Management

This document is a part of a REST API guide for the workforceos project. It is designed for AI agents that will generate frontend code to consume the project’s backend.

This document includes the verification processes for the autheitcation flow. Please read it carefully and implement all requirements described here.

The project has 1 auth service, 1 notification service, 1 BFF service, and 10 business services, plus other helper services such as bucket and realtime. In this document you will be informed only about the auth service.

Each service is a separate microservice application and listens for HTTP requests at different service URLs.

Services may be deployed to the preview server, staging server, or production server. Therefore, each service has 3 access URLs. The frontend application must support all deployment environments during development, and the user should be able to select the target API server on the home page.

Accessing the backend

Each backend service has its own URL for each deployment environment. Users may want to test the frontend in one of the three deployments—preview, staging, or production. Please ensure that the home page includes a deployment server selection option so that, as the frontend coding agent, you can set the base URL for all services.

For the auth service, the base URLs are:

Any request that requires login must include a valid token in the Bearer authorization header.

Multi-Tenancy Management

THIS APPLICATION IS MULTI-TENANT

This application is mult-tanant, it means; as a SaaS application, it isolates each tenant-data from each other. The tenants are called company and a data object with the same name exist to store and manage the tenant information. The company data instances are referenced from other data objects or entities as companyId. Any data object which is in tenant level (some data objects may still stay in SaaS level) has a companyId property which attaches it to a company tenant. But this value is added to the data object instance in the time of creation by the system according to the current company user is navigating.

For the human readability each company has also got a companyCodename which is a unique form of its name. Any api call to the application should claim its target company tenant, so it should provide companyCodename parameter at one of the following request locations.

// In header with special header name
headers["mbx-company-codename"] = "babil",

// or in query with ( _company ) parameter

const url = `${serviceUrl}/v1/users/${userId}?_company=babil`

// or in post body with ( _company ) parameter
const body = {
  //...
  _company: "babil",
  //...
}

When no companyCodename is given in the related parameters, application will assume that the access targets the root target, the Saas level. The companyCodename of SaaS level is always root. When no companyCodename is specified, root is assumed as the current companyCodename.

Note that, logins and registrations are all tenant scoped. If any a tenant-lvel api is login-required then it will check for a company specific token according to the target company defined in a related parameter with its codename. The application creates the cookies with companyCodename prefixes but it is recommended for the frontend application to populate the bearer header with the user’s company related token.

Not that all company tenants are managed in the same backend services, however a company tanant frontend should be specific to one company. Frontend should have a technical way to understand which company is targeted by the user, for production frontend application this should be managed by the subdomains that represents the codename of the company like,

https://babil.storeCreator.com

Using the subdomain, frontend will distinguish that the codename is babil and will atatch it to all tenant-level api calls.

The url may also be used for the SaaS directly with a more general wording like,

https://www.storeCreator.com

However, this subdomain management may not be handled easily in the AI frontend builders that they use their own preview urls, an other url structure should be handled to simulate the subdomain behaviour for tenant forwarding.

It may be like,

https://{somePreviewUrlOfABuilderPlatform}/babil/login

In some way, frontend should provide a simple and practical way to the user to target a specific tenant.

Sample Company Tenant

The applcation backend also includes a sample tenant created with a sample tenant owner, who has the same login identifier and password as the superadmin. This sample is created in the backend to be able to test the multi-tenant behaviour of the frontend at the beginning.

The sample company has a codename babil and can be targetd by attaching this codename to the API calls. So whwn the front end home page is built, homepages both for the SaaS and tenant shoul be created and ready to be tested.

After User Registration

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.

Parameter Type Required Description
email String Yes User’s email address to verify

Example Request

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

Success Response

{
  "status": "OK",
  "codeIndex": 1,
  "timeStamp": 1784578660000,
  "date": "Mon Jul 20 2026 23:17:40 GMT+0300 (GMT+03:00)",
  "expireTime": 86400,
  "verificationType": "byLink",
  "secretCode": "123456",
  "userId": "user-uuid"
}

⚠️ In production, secretCode is not returned — it is only sent via email.

Error Responses

POST /verification-services/email-verification/complete

Purpose: Completes verification using the received code.

Parameter Type Required Description
email String Yes User’s email
secretCode String Yes Verification code

Success Response

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

Error Responses

Resetting Password

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

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

Parameter Type Required Description
email String Yes The email address of the user 
{
  "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

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

Parameter Type Required Description
email String Yes The email address of the user
secretCode String Yes The code received via email
password String Yes The new password the user wants to set 
{
  "email": "user@example.com",
  "secretCode": "123456",
  "password": "newSecurePassword123"
}

Success Response

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

Error Responses

Two-Factor Authentication (2FA)

This project has email two-factor authentication enabled. 2FA is different from email/mobile verification: verification proves ownership during registration (one-time), while 2FA runs on every login as an additional security layer.

How 2FA Works After Login

When a user logs in successfully, the login response includes accessToken, userId, sessionId, and all session data. However, when 2FA is active, the response also contains one or both of these flags:

When any of these flags are true, the session is NOT fully authorized. The accessToken is valid only for calling the 2FA verification endpoints. All other protected API calls will return 403 Forbidden with error code EmailTwoFactorNeeded or MobileTwoFactorNeeded until 2FA is completed.

2FA Frontend Flow

  1. After a successful login, check the response for sessionNeedsEmail2FA or sessionNeedsMobile2FA (login returns 200 with the full session — accessToken, userId, sessionId and all user fields — plus the 2FA flag).
  2. If either flag is true, do not treat the user as authenticated and do not navigate to the app home. The token from useLogin is already stored automatically; it’s a partial token though — the backend’s enforce2FA(session) will reject every protected call with EmailTwoFactorNeeded / MobileTwoFactorNeeded 403 until the 2FA flag is cleared. Only the 2FA verification endpoints (and /currentuser) accept it as-is.
  3. Navigate the user to a 2FA verification page instead of /.
  4. On the 2FA page, immediately call the 2FA start endpoint (described below). The user / session are read from the auth header — no userId or sessionId in the payload. This triggers sending the verification code to the user’s email.
  5. Display a 6-digit code input. If the response contains secretCode (test/development mode), display it on the page so the user can copy and paste it.
  6. The start response includes a codeIndex property. Display its value on the page so the user can match the index in the message with the one on the screen.
  7. When the user submits the code, call the 2FA complete endpoint with just secretCode in the body (the auth header carries the user / session identity).
  8. On success, the complete endpoint returns the updated session object with the 2FA flag cleared. Now set the user as fully authenticated and navigate to the main application page.
  9. Provide a “Resend Code” button with a 60-second cooldown to prevent spam.
  10. Provide a “Cancel” option that discards the partial session and returns the user to the login page.

Email 2FA Endpoints

POST /verification-services/email-2factor-verification/start

Purpose: Starts email-based 2FA by generating and sending a verification code to the user’s email.

Parameter Type Required Description
userId String Yes The user’s ID
sessionId String Yes The current session ID

Example Request

{
  "userId": "user-uuid",
  "sessionId": "session-uuid"
}

Success Response

{
  "status": "OK",
  "sessionId": "session-uuid",
  "userId": "user-uuid",
  "codeIndex": 1,
  "timeStamp": 1784578660000,
  "date": "Mon Jul 20 2026 23:17:40 GMT+0300",
  "expireTime": 86400,
  "verificationType": "byCode",

  // in testMode only
  "secretCode": "123456"
}

⚠️ In production, secretCode is not returned — it is only sent via email.

Error Responses

POST /verification-services/email-2factor-verification/complete

Purpose: Completes email 2FA by validating the code and clearing the session 2FA flag.

Parameter Type Required Description
userId String Yes The user’s ID
sessionId String Yes The session ID
secretCode String Yes Verification code from email

Success Response

Returns the updated session with sessionNeedsEmail2FA: false:

{
  "sessionId": "session-uuid",
  "userId": "user-uuid",
  "email": "user@example.com",
  "fullname": "John Doe",
  "roleId": "user",
  "sessionNeedsEmail2FA": false,
  "accessToken": "jwt-token",
  "...": "..."
}

Error Responses

Important 2FA Notes

Navigating 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 company. If this login navigate is after a user registration (or after a post-registration verification) to a company, then keep the active company as the original and navigate user to the selected company. If this login navigate is after a company registration (or after a tenant post-registration verification), then you have a new company 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 company that the previous login attempt is made to and navigate to the same company either it is the root or andy registered company.

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

After this prompt, the user may give you new instructions to update your first output or provide subsequent prompts about the project.