WORKFORCEOS

FRONTEND GUIDE FOR AI CODING AGENTS - PART 2 - Authentication Management

This document covers the authentication features of the workforceos project: registration, login, logout, and session management. The project introduction, API conventions, home page, and multi-tenancy setup were covered in the previous introductory prompt — make sure those are implemented before proceeding.

All auth APIs use the auth service base URL with the /auth-api prefix (e.g., https://workforceos.mindbricks.co/auth-api).

FRONTEND_URL

The FRONTEND_URL environment variable is automatically set on the auth service from the project’s frontendUrl setting in Basic Project Settings. It is used by the auth service for:

Defaults if not configured:

Environment Default
dev http://localhost:5173
test https://workforceos.prw.mindbricks.com
stage https://workforceos-stage.mindbricks.co
prod https://workforceos.mindbricks.co

You can customize FRONTEND_URL per environment by configuring the frontendUrl field in your project’s Basic Project Settings (e.g., when using a custom domain).

Registration Management

Since the application is multi-tenant, there will be two registration process. First one is the company register and the other one is user registration.

Users are either in SaaS level, like administrators, or in company tenant level like company owners, admins and users.

SaaS Level User Registration

SaaS user registration is not public in the application, SaaS users can only be created through createUser api which can be called by the superAdmin or saasAdmin of the SaaS level. Creating a new SaaS user is handled through admin panel which will be described in the next prompt.

SaaS users belong to root tenant context and should login from the SaaS entry page. Tenant-end users should not use this login entry.

Tenant -company- Registration

Tenant registraration, creating a new company, is always handled together with tenant owner registration.

Both tenant and tenant owner registration are public in the application, so there will be a company registration page in the frontend, that any user can provide their user and company information together.

Using the registercompanyOwner route of the auth API, send the required fields from your registration page. Please create a simple and polished registration page that includes only the necessary fields of the registration API.

The registerCompanyOwner API in the auth service is described with the request and response structure below.

Note that since the registerCompanyOwner API is a business API, it is versioned; call it with the given version like /v1/registercompanyOwner.

Registering a company and its owner is indeed a user registration which also creates a company and assigns its ownership to the created user. The created user instance will have got the id of the company in its `companyId property automatically.

The provided api body should also include a nested object for the company data object instance to be created.

{
  //..
  "email": "joe.doe@example.com",
  "fullname": "Joe Doe",
  "avatar": "...",
  //..
  "company": {
    //.. 
    "name": "Babil",
    "fullname": "Babil Online BookStore Ltd.",
    "avatar": "..."
  }
}

Register Companyowner API

This api is used by public users to register themselves as tenant owners to create both a user account and a company account they own.

Rest Route

The registerCompanyOwner API REST controller can be triggered via the following route:

/v1/registercompanyowner

Rest Request Parameters

The registerCompanyOwner api has got 6 regular request parameters

Parameter Type Required Population
avatar String false request.body?.[“avatar”]
socialCode String false request.body?.[“socialCode”]
password String true request.body?.[“password”]
email String true request.body?.[“email”]
company Object true request.body?.[“company”]
fullname String true request.body?.[“fullname”]
avatar : The avatar url of the user. If not sent, a default random one will be generated.
socialCode : Send this social code if it is sent to you after a social login authetication of an unregistred user. The users profile data will be complemented from the autheticated social profile using this code. If you provide the social code there is no need to give full profile data of the user, just give the ones that are not included in social profiles.
password : The password defined by the the user that is being registered.
email : The email defined by the the user that is being registered.
company : The company informatiion for the tenant that the created user will own.
fullname : The full name defined by the the user that is being registered.

REST Request To access the api you can use the REST controller with the path POST /v1/registercompanyowner

  axios({
    method: 'POST',
    url: '/v1/registercompanyowner',
    data: {
            avatar:"String",  
            socialCode:"String",  
            password:"String",  
            email:"String",  
            company:"Object",  
            fullname:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	},
	"company": "Object"
}

After a successful registration, the frontend code should handle verification requirements with the same flow style as single-tenant mode. The registration response will include a user object in the root envelope; this object contains user information with an id field.

Tenant -company- User Registration

User registration for company tenants is public in the application. Please create a simple and polished registration page that includes only the necessary fields of the registration API.

This registration targets an existing company, so the tenant context must be provided — attach the company codename to the request header.

Using the registercompanyuser route of the auth API, send the required fields from your registration page.

The registerCompanyUser API in the auth service is described with the request and response structure below.

Note that since the registerCompanyUser API is a business API, it is versioned; call it with the given version like /v1/registercompanyuser.

Register Companyuser API

This route is used by public users to register themselves to tenants that are created by tenant owners.

Rest Route

The registerCompanyUser API REST controller can be triggered via the following route:

/v1/registercompanyuser

Rest Request Parameters

The registerCompanyUser api has got 5 regular request parameters

Parameter Type Required Population
socialCode String false request.body?.[“socialCode”]
password String true request.body?.[“password”]
email String true request.body?.[“email”]
fullname String true request.body?.[“fullname”]
avatar String false request.body?.[“avatar”]
socialCode : Send this social code if it is sent to you after a social login authetication of an unregistred user. The users profile data will be complemented from the autheticated social profile using this code. If you provide the social code there is no need to give full profile data of the user, just give the ones that are not included in social profiles.
password : The password defined by the the user that is being registered.
email : The email defined by the the user that is being registered.
fullname : The full name defined by the the user that is being registered.
avatar : The avatar url of the user. A random avatar will be generated if not provided

REST Request To access the api you can use the REST controller with the path POST /v1/registercompanyuser

  axios({
    method: 'POST',
    url: '/v1/registercompanyuser',
    data: {
            socialCode:"String",  
            password:"String",  
            email:"String",  
            fullname:"String",  
            avatar:"String",  
    
    },
    params: {
    
        }
  });

REST Response

{
	"status": "OK",
	"statusCode": "201",
	"elapsedMs": 126,
	"ssoTime": 120,
	"source": "db",
	"cacheKey": "hexCode",
	"userId": "ID",
	"sessionId": "ID",
	"requestId": "ID",
	"dataName": "user",
	"method": "POST",
	"action": "create",
	"appVersion": "Version",
	"rowCount": 1,
	"user": {
		"id": "ID",
		"email": "String",
		"password": "String",
		"fullname": "String",
		"avatar": "String",
		"roleId": "String",
		"emailVerified": "Boolean",
		"companyId": "ID",
		"isActive": true,
		"recordVersion": "Integer",
		"createdAt": "Date",
		"updatedAt": "Date",
		"_owner": "ID"
	}
}

After a successful registration, the frontend code should handle verification requirements with the same flow style as single-tenant mode. Verification Management will be given in the next prompt. The registration response will include a user object in the root envelope; this object contains user information with an id field.

Login Management

Login Identifier Model

The primary login identifier for this application is the email address. Users register and log in using their email and password. No mobile field is stored in the user data model. The login page should include an email input and a password input.

Login Flow

After successful registration and completing any required verifications, the user can log in. Please create a minimal, polished login page as described above.

Note that this page should respect the deployment (environment) selection option made in the home page to set the base URL. If the user reaches this page directly skipping home page, the default production deployment will be used.

The login API returns a created session. This session can be retrieved later with the access token using the /currentuser system route.

Any request that requires login must include a valid token. When a user logs in successfully, the response JSON includes a JWT access token in the accessToken field. Under normal conditions, this token is also set as a cookie and consumed automatically. However, since AI coding agents’ preview options may fail to use cookies, ensure that each request includes the access token in the Bearer authorization header.

If the login fails due to verification requirements, the response JSON includes an errCode. If it is EmailVerificationNeeded, start the email verification flow; if it is MobileVerificationNeeded, start the mobile verification flow.

After a successful login, you can access session (user) information at any time with the /currentuser API. On inner pages, show brief profile information (avatar, name, etc.) using the session information.

Note that the session/currentuser response has no id property; instead, the values for the user and session are exposed as userId and sessionId. The response combines user and session information.

The login, logout, and currentuser APIs are as follows. They are system routes and are not versioned.

POST /login — User Login

Purpose: Verifies user credentials and creates an authenticated session with a JWT access token.

Access Routes:

Request Parameters

Parameter Type Required Source
username String Yes request.body.username
password String Yes request.body.password

Behavior

Example

axios.post("/login", {
  email: "user@example.com",
  password: "securePassword"
});

Success Response

{
  "sessionId": "e81c7d2b-4e95-9b1e-842e-3fb9c8c1df38",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  //...
  "accessToken": "ey7....",
  "userBucketToken": "e56d....",
  "sessionNeedsEmail2FA": true,
  "sessionNeedsMobile2FA": true,

}

Note on bucket tokens: The userBucketToken is for the external bucket service (used for general file uploads like documents and product images). User avatars do not use the external bucket service — they are uploaded via database buckets (dbBuckets) built into the auth service using the regular accessToken. See the Profile or Bucket Management sections for dbBucket avatar upload details.

Two-Factor Authentication (2FA): When the login response contains sessionNeedsEmail2FA: true or sessionNeedsMobile2FA: true, the session is not yet fully authorized. The accessToken is valid but all protected API calls will return 403 until 2FA is completed. Do not treat this login as successful — instead, store the accessToken, userId, and sessionId, and navigate the user to a 2FA verification page. The 2FA flow details are covered in the Verification Management prompt.

Error Responses

POST /logout — User Logout

Purpose: Terminates the current session and clears associated authentication tokens.

Behavior

Example

axios.post("/logout", {}, {
  headers: { "Authorization": "Bearer your-jwt-token" }
});

Notes

Success Response

{ "status": "OK", "message": "User logged out successfully" }

GET /currentuser — Current Session

Purpose Returns the currently authenticated user’s session.

Route Type sessionInfo

Authentication Requires a valid access token (header or cookie).

Request

No parameters.

Example

axios.get("/currentuser", {
  headers: { Authorization: "Bearer <jwt>" }
});

Success (200)

Returns the session object (identity, tenancy, token metadata):

{
  "sessionId": "9cf23fa8-07d4-4e7c-80a6-ec6d6ac96bb9",
  "userId": "d92b9d4c-9b1e-4e95-842e-3fb9c8c1df38",
  "email": "user@example.com",
  "fullname": "John Doe",
  "roleId": "user",
  "tenantId": "abc123",
  "accessToken": "jwt-token-string",
  "...": "..."
}

Note that the currentuser API returns a session object, so there is no id property, instead, the values for the user and session are exposed as userId and sessionId. The response is a mix of user and session information.

Errors

Notes

After you complete this step, please ensure you have not made the following common mistakes:

  1. The raw /currentuser API mixes session and user data into a single flat envelope. There is no id property on the raw response — use userId and sessionId.
  2. Note that any API call to the auth service should use the /auth-api prefix after the application’s base URL.

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