Identity Module

Identity Module

The Identity module handles authentication, user management, roles and permissions, multi-tenancy, companies, branches, profiles, sessions, and API keys.

Client Access

var identity = essabu.identity();

Available API Classes

Class	Accessor	Description
AuthApi	identity.auth()	Authentication, registration, 2FA
UserApi	identity.users()	User management
RoleApi	identity.roles()	Role management
PermissionApi	identity.permissions()	Permission management
TenantApi	identity.tenants()	Tenant management
CompanyApi	identity.companies()	Companies and company groups
BranchApi	identity.branches()	Branch management
ProfileApi	identity.profiles()	User profile operations
SessionApi	identity.sessions()	Session management
ApiKeyApi	identity.apiKeys()	API key management

---

AuthApi

Method	Endpoint	Description
login(Map)	POST /api/identity/auth/login	Authenticate and get tokens
refresh(Map)	POST /api/identity/auth/refresh	Refresh access token
register(Map)	POST /api/identity/auth/register	Register a new account
verifyEmail(Map)	POST /api/identity/auth/verify-email	Verify email address
forgotPassword(Map)	POST /api/identity/auth/forgot-password	Request password reset
resetPassword(Map)	POST /api/identity/auth/reset-password	Reset password
logout()	DELETE /api/identity/auth/logout	Logout
enable2FA(Map)	POST /api/identity/auth/2fa/enable	Enable two-factor auth
verify2FA(Map)	POST /api/identity/auth/2fa/verify	Verify 2FA code
generateRecoveryCodes()	POST /api/identity/auth/2fa/recovery-codes	Generate recovery codes
get2FAStatus()	GET /api/identity/auth/2fa/status	Get 2FA status

Map tokens = identity.auth().login(Map.of("email", "user@example.com", "password", "secret"));
Map qr = identity.auth().enable2FA(Map.of());
identity.auth().verify2FA(Map.of("code", "123456"));

UserApi

Standard CRUD at /api/identity/users:

Map user = identity.users().create(Map.of(
    "email", "new@example.com", "firstName", "Jane", "lastName", "Doe", "roleId", roleId
));

CompanyApi

Companies and company groups at /api/identity/companies and /api/identity/company-groups.

ApiKeyApi

Method	Endpoint	Description
list(PageRequest)	GET /api/identity/api-keys	List API keys
create(Map)	POST /api/identity/api-keys	Create API key
revoke(UUID)	DELETE /api/identity/api-keys/{id}	Revoke API key

Additional CRUD APIs

RoleApi, PermissionApi, TenantApi, BranchApi -- standard CRUD operations.

ProfileApi -- getMyProfile() and updateMyProfile(Map).

SessionApi -- list(), revoke(UUID), revokeAll().

Error Scenarios

HTTP Status	Cause
400	Invalid request data (bad email, weak password)
401	Invalid credentials or expired token
403	Insufficient permissions
404	User, role, or resource not found
409	Conflict (duplicate email, role name)
429	Rate limit exceeded (login attempts)