Auth Service Generated Assets

The auth service is automatically generated when you configure the Authentication module in your Mindbricks project. This service provides user management, authentication, authorization, and multi-tenancy capabilities.

Automatic Data Objects

The auth service automatically includes the following data objects:

1. user Data Object

The user data object is the core entity for user management. It is always present in the auth service.

Naming Convention:

• Data Object Name: user
• Model Name: User (PascalCase)
• Service Reference: auth:user (when referenced from other services)

System-Owned Properties:

Custom Properties: Architects can add custom properties via ProjectAuthentication.userProperties array. These properties follow standard DataProperty pattern definitions.

Initial Data:

• Super Admin User: Automatically created on deployment with credentials defined in LoginDefUserSettings.superAdminEmail and LoginDefUserSettings.superAdminPassword

2. userGroup Data Object (Conditional)

The userGroup data object is generated when userGroupsActive is set to true in LoginDefUserSettings.

Naming Convention:

• Data Object Name: userGroup
• Model Name: UserGroup (PascalCase)
• Service Reference: auth:userGroup

System-Owned Properties:

3. userGroupMember Data Object (Conditional)

The userGroupMember data object is generated when userGroupsActive is set to true. It manages the many-to-many relationship between users and groups.

Naming Convention:

• Data Object Name: userGroupMember
• Model Name: UserGroupMember (PascalCase)
• Service Reference: auth:userGroupMember

System-Owned Properties:

4. ROLES System Object

Roles in Mindbricks are not stored as data objects but as a system object (constant/enum) that defines available role names and their values. This ROLES object is always present in the auth service, regardless of whether RBAC is active.

System Roles (Always Available):

Single-Tenant Projects:

• superAdmin — Super administrator with full system access
• admin — Administrator with elevated permissions
• user — Standard user role

Multi-Tenant (SaaS) Projects:

• superAdmin — Super administrator at SaaS level
• saasAdmin — SaaS-level administrator
• saasUser — SaaS-level user
• tenantOwner — Owner of a tenant
• tenantAdmin — Administrator within a tenant
• tenantUser — Standard user within a tenant

Custom Roles (When RBAC is Active):

When rbacIsActive is true, architects can define additional custom roles via AccessControl.roleSettings.configuration.rolesObject array. Each role is defined with:

• name — Display name (used in UIs and documentation)
• value — Role value stored in user.roleId and session

Example Custom Roles Configuration:

{
  "authentication": {
    "accessControl": {
      "roleSettings": {
        "rbacIsActive": true,
        "configuration": {
          "rolesObject": [
            { "name": "Manager", "value": "manager" },
            { "name": "Editor", "value": "editor" },
            { "name": "Viewer", "value": "viewer" }
          ]
        }
      }
    }
  }
}

Usage in Business Logic:

Role names (both system and custom) are assets that should be referenced in authorization business logic:

• In MScript expressions: this.session.roleId === "admin"
• In Business API auth options: requiredRole: "admin"
• In permission checks: PermissionCheckAction with role-based conditions
• In access control rules: Role-based where clauses and filters

Note: The user.roleId property stores the role value (not the role name). When usersHaveMultipleRoles is enabled, roleId becomes an array of role values.

5. givenPermission Data Object (Conditional)

The givenPermission data object is generated when Permission-Based Access Control (PBAC) is active (pbacIsActive is true). This data object stores permission assignments — it records which permissions are granted to roles, user groups, users, or specific objects.

Naming Convention:

• Data Object Name: givenPermission
• Model Name: GivenPermission (PascalCase)
• Service Reference: auth:givenPermission

System-Owned Properties:

Note: Permissions themselves are hardcoded/defined in the PBAC configuration via PermissionGroups in AccessControl.permissionSettings.configuration.permissionGroups. The givenPermission data object only stores assignments of these predefined permissions to roles, users, groups, or objects.

6. tenant Data Object (Conditional)

The tenant data object is generated when multi-tenancy is active (useMultiTenantFeature is true).

Naming Convention:

• Data Object Name: {tenantName} (e.g., client, store, workspace)
• Model Name: {TenantName} (PascalCase, e.g., Client, Store, Workspace)
• Service Reference: auth:{tenantName}

System-Owned Properties:

Custom Properties: Architects can add custom properties via ProjectAuthentication.tenantProperties array.

Initial Data:

• Root Tenant: Automatically created with codename "root" for SaaS-level operations

Automatic Business APIs and REST Routes

Mindbricks automatically generates Business APIs for the auth service data objects. The REST routes are generated based on the API name and crudType, following RESTful conventions.

For detailed route generation rules, see the Introduction document.

User Data Object APIs

Note:

• Replace {TenantName} with the actual tenant name (e.g., Client, Store, Workspace)
• registerUser is only generated when userRegisterIsPublic is true and multi-tenancy is disabled
• register{TenantName}Owner and register{TenantName}User are only generated when multi-tenancy is active
• All user APIs have gRPC controllers enabled

UserGroup Data Object APIs (if userGroupsActive is true)

UserGroupMember Data Object APIs (if userGroupsActive is true)

GivenPermission Data Object APIs (if pbacIsActive is true)

Tenant Data Object APIs (if multi-tenancy is active)

Note: Replace {TenantName} with the actual tenant name (e.g., Client, Store, Workspace). The route uses the pluralized form (e.g., /auth/clients, /auth/stores).

Auth Service Additional Routes

The auth service includes additional authentication and session management routes beyond the common session routes. These are mounted at /auth-api (without version).

Query Parameters:

• /getusersessions — Optional userId query parameter (defaults to current user)
• /getuserhistory — Optional userId query parameter (defaults to current user)
• /deleteusersession/:sessionId — Optional userId query parameter (defaults to current user)
• /deleteallsessions — Optional userId query parameter (defaults to current user)

Path Parameters:

• /deleteusersession/:sessionId — The session ID to delete

Request Body (POST /login):

{
  "username": "user@example.com",  // or "email"
  "password": "userpassword"
}

Response (POST /login):

• Returns session object with JWT token and user information
• Sets HTTP-only cookie with access token
• May include cookieError if cookie setting fails

For common session routes available in all services, see General Service Assets.

Automatic Verification Service Routes

Mindbricks automatically generates verification service routes when the corresponding verification features are activated in the VerificationServices configuration. These routes are mounted at /auth-api/verification-services (without version prefix) and are only active when their respective isActive flags are set to true in the pattern design.

Note: All verification routes are system routes and therefore are not versioned. The /verification-services router is mounted to /auth-api, so the full route paths are /auth-api/verification-services/{service}/{action}.

Email Verification Routes

Activation Condition: VerificationServices.emailVerification.emailVerificationIsActive must be true

Request Body (/start):

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

Request Body (/complete):

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

Response (/start):

• Returns codeIndex, timeStamp, date, expireTime, verificationType
• In test mode: also returns secretCode and userId

Response (/complete):

• Returns status: "OK", isVerified: true, email
• In test mode: also returns userId

Mobile Verification Routes

Activation Condition: VerificationServices.mobileVerification.mobileVerificationIsActive must be true

Request Body (/start):

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

Request Body (/complete):

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

Response (/start):

• Returns codeIndex, timeStamp, date, expireTime, verificationType, masked mobile
• In test mode: also returns secretCode and userId

Response (/complete):

• Returns status: "OK", isVerified: true, email
• In test mode: also returns userId and mobile

Email 2-Factor Authentication Routes

Activation Condition: VerificationServices.email2Factor.email2FactorIsActive must be true

Request Body (/start):

{
  "userId": "user-uuid",
  "sessionId": "session-uuid",
  "reason": "login",
  "client": "web"
}

Request Body (/complete):

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

Response (/start):

• Returns status: "OK", sessionId, userId, codeIndex, timeStamp, date, expireTime, verificationType
• In test mode: also returns secretCode

Response (/complete):

• Returns the updated session object with sessionNeedsEmail2FA: false

Mobile 2-Factor Authentication Routes

Activation Condition: VerificationServices.mobile2Factor.mobile2FactorIsActive must be true

Request Body (/start):

{
  "userId": "user-uuid",
  "sessionId": "session-uuid",
  "reason": "login",
  "client": "web"
}

Request Body (/complete):

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

Response (/start):

• Returns status: "OK", sessionId, userId, codeIndex, timeStamp, date, expireTime, verificationType
• In test mode: also returns secretCode

Response (/complete):

• Returns the updated session object with sessionNeedsMobile2FA: false

Password Reset by Email Routes

Activation Condition: VerificationServices.passwordResetByEmail.passwordResetByEmailIsActive must be true

Request Body (/start):

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

Request Body (/complete):

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

Response (/start):

• Returns status: "OK", codeIndex, timeStamp, date, expireTime, verificationType
• In test mode: also returns secretCode and userId

Response (/complete):

• Returns status: "OK", isVerified: true, email
• In test mode: also returns userId
• Automatically sets emailVerified: true on the user

Password Reset by Mobile Routes

Activation Condition: VerificationServices.passwordResetByMobile.passwordResetByMobileIsActive must be true

Request Body (/start):

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

Request Body (/complete):

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

Response (/start):

• Returns status: "OK", codeIndex, timeStamp, masked mobile, date, expireTime, verificationType
• In test mode: also returns secretCode and userId

Response (/complete):

• Returns status: "OK", isVerified: true, mobile
• In test mode: also returns userId
• Automatically sets mobileVerified: true on the user

Important Notes:

• All verification routes are rate-limited (typically 60 seconds between requests)
• Verification codes expire based on the expireTimeWindow configuration
• In test mode (VerificationSettings.verificationMode: "testMode"), secret codes are returned in responses for development purposes
• In live mode (VerificationSettings.verificationMode: "liveMode"), secret codes are only sent via email/SMS
• Each verification service publishes Kafka events on start and complete actions (see Kafka Topics section below)

Generated Kafka Topics

Database Event Topics

For each data object in the auth service, Kafka topics are automatically generated for database-level events:

User Data Object Topics (DB Events)

Example: If project code name is myproject, the topics would be:

• myproject-auth-service-dbevent-user-created
• myproject-auth-service-dbevent-user-updated
• myproject-auth-service-dbevent-user-deleted

UserGroup Data Object Topics (DB Events, if userGroupsActive is true)

UserGroupMember Data Object Topics (DB Events, if userGroupsActive is true)

GivenPermission Data Object Topics (DB Events, if pbacIsActive is true)

Tenant Data Object Topics (DB Events, if multi-tenancy is active)

Note: Replace {tenantName} with the actual tenant name (e.g., client, store, workspace).

Business API Event Topics (if raiseApiEvent is true)

Business APIs that have raiseApiEvent set to true (default) publish events to topics following the pattern: {projectCodeName}-auth-service-{resource}-{actionPassiveForm}

Examples:

• login API → {projectCodeName}-auth-service-user-logged-in (if resource is "user")
• registerUser API → {projectCodeName}-auth-service-user-registered (if resource is "user")
• updateUserRole API → {projectCodeName}-auth-service-userrole-updated (if resource is "userRole")

Note: The exact topic name depends on the API's resource name and action passive form. Not all Business APIs necessarily publish events (depends on raiseApiEvent setting).

Verification Service Event Topics

When verification services are active, they automatically publish Kafka events on start and complete actions. These events are published using the ServicePublisher and include the verification data, session (when available), and request ID. These topics follow the pattern: {projectCodeName}-auth-service-{verificationType}-{action}

Event Publishing Details:

• Start Events: Published immediately after a verification process is initiated (when /start route is called successfully)
• Complete Events: Published immediately after a verification process is successfully completed (when /complete route is called successfully and verification code matches)
• Session Attachment: Session object is automatically attached to the Kafka message when available (for authenticated routes like 2FA)
• Message Structure: Each event includes the full verification data object with user information, timestamps, and verification metadata

Email Verification Topics (if emailVerificationIsActive is true)

Mobile Verification Topics (if mobileVerificationIsActive is true)

Email 2FA Topics (if email2FactorIsActive is true)

Mobile 2FA Topics (if mobile2FactorIsActive is true)

Password Reset by Email Topics (if passwordResetByEmailIsActive is true)

Password Reset by Mobile Topics (if passwordResetByMobileIsActive is true)

Note: Replace {projectCodeName} with your actual project code name. These topics are only created when the corresponding verification service is activated in the VerificationServices configuration.

Database Utility Functions

For each data object in the auth service, Mindbricks generates database utility functions in the dbLayer module. These follow the standard naming convention:

Function Pattern: {operation}{ModelName}

User Data Object Functions

const {
  createUser,
  createBulkUser,
  getUserById,
  getUserAggById,
  getUserListByQuery,
  getUserByQuery,
  getUserStatsByQuery,
  getIdListOfUserByField,
  updateUserById,
  updateUserByIdList,
  updateUserByQuery,
  deleteUserById,
  deleteUserByQuery
} = require("dbLayer");

UserGroup Data Object Functions (if userGroupsActive is true)

const {
  createUserGroup,
  createBulkUserGroup,
  getUserGroupById,
  getUserGroupAggById,
  getUserGroupListByQuery,
  getUserGroupByQuery,
  getUserGroupStatsByQuery,
  getIdListOfUserGroupByField,
  updateUserGroupById,
  updateUserGroupByIdList,
  updateUserGroupByQuery,
  deleteUserGroupById,
  deleteUserGroupByQuery
} = require("dbLayer");

UserGroupMember Data Object Functions (if userGroupsActive is true)

const {
  createUserGroupMember,
  createBulkUserGroupMember,
  getUserGroupMemberById,
  getUserGroupMemberAggById,
  getUserGroupMemberListByQuery,
  getUserGroupMemberByQuery,
  getUserGroupMemberStatsByQuery,
  getIdListOfUserGroupMemberByField,
  updateUserGroupMemberById,
  updateUserGroupMemberByIdList,
  updateUserGroupMemberByQuery,
  deleteUserGroupMemberById,
  deleteUserGroupMemberByQuery
} = require("dbLayer");

GivenPermission Data Object Functions (if pbacIsActive is true)

const {
  createGivenPermission,
  createBulkGivenPermission,
  getGivenPermissionById,
  getGivenPermissionAggById,
  getGivenPermissionListByQuery,
  getGivenPermissionByQuery,
  getGivenPermissionStatsByQuery,
  getIdListOfGivenPermissionByField,
  updateGivenPermissionById,
  updateGivenPermissionByIdList,
  updateGivenPermissionByQuery,
  deleteGivenPermissionById,
  deleteGivenPermissionByQuery
} = require("dbLayer");

Tenant Data Object Functions (if multi-tenancy is active)

Similar functions are generated for the tenant data object (e.g., createClient, getClientById, etc., where Client is the tenant name).

Note: There are no database utility functions for roles, as roles are system constants, not data objects.

For detailed documentation on all database utility functions, see the Database Utility Functions guide.

Automatically Populated Initial Data

Super Admin User

On deployment, Mindbricks automatically creates a Super Admin user with:

• Email: Value from LoginDefUserSettings.superAdminEmail
• Password: Value from LoginDefUserSettings.superAdminPassword
• Role: superAdmin (system role)
• Email Verified: true
• Full Access: Complete system access across all services and tenants

Root Tenant (Multi-Tenant Only)

When multi-tenancy is active, a root tenant is automatically created:

• Codename: "root"
• Fullname: "Root" (or as configured)
• Purpose: SaaS-level operations and global administration

Related Documentation

• Introduction — Naming conventions and general patterns
• General Service Assets — Common assets for all services
• Database Utility Functions — Detailed function documentation