Authentication

The Vendor App supports multiple authentication methods for different user types within a vendor organization.

User Types

Type	Description	Login Method
Vendor Owner	Primary account holder	Email/Phone + Password
Sub-user	Team member with assigned role	Username + Password

Login Flow

Owner Login

┌─────────────────┐
│  Enter Email    │
│  or Phone       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Enter Password │
│                 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌─────────────────┐
│  2FA (if        │────▶│  Enter OTP      │
│  enabled)       │     │                 │
└────────┬────────┘     └────────┬────────┘
         │                       │
         └───────────┬───────────┘
                     ▼
            ┌─────────────────┐
            │  Select Till    │
            │  (if multiple)  │
            └────────┬────────┘
                     │
                     ▼
            ┌─────────────────┐
            │   Dashboard     │
            └─────────────────┘

Sub-user Login

┌─────────────────┐
│  Enter Username │
│                 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Enter Password │
│                 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Load Assigned  │
│  Till & Perms   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   Dashboard     │
│   (Limited)     │
└─────────────────┘

First-Time Password Setup

New sub-users must set their password on first login:

┌─────────────────┐
│  Enter Temp     │
│  Code (from SMS)│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Create New     │
│  Password       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Confirm New    │
│  Password       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Account Ready  │
│                 │
└─────────────────┘

Controller Methods

Method	Description
loginAsOwner(identifier, password)	Owner login
loginAsSubUser(username, password)	Sub-user login
setPassword(tempCode, newPassword)	First-time password setup

Permission Checks

Permission	Description
canAcceptPayments	POS permission
canTopUp	Top-up permission
canWithdraw	Withdrawal permission
canViewAllTransactions	View all transactions
canExport	Export reports
canManageTeam	Team management
canManageCards	Card operations

Password Requirements

Requirement	Rule
Length	Minimum 8 characters
Uppercase	At least 1
Lowercase	At least 1
Number	At least 1
Special	At least 1 (!@#$%^&*)

Session Management

Token Storage

Key	Description
vendor_access_token	Access token
vendor_refresh_token	Refresh token
active_till_id	Active till ID

Auto-Logout

The app automatically logs out after:

• 15 minutes of inactivity
• App backgrounded for 5+ minutes
• Token expiration

API Endpoints

Endpoint	Method	Description
/vendor/auth/login	POST	Owner login
/vendor/auth/subuser-login	POST	Sub-user login
/vendor/auth/set-password	POST	First-time password
/vendor/auth/verify-otp	POST	2FA verification
/vendor/auth/forgot-password	POST	Password reset
/vendor/auth/refresh	POST	Refresh token
/vendor/auth/logout	POST	End session

Error Handling

Error	Cause	Action
VAUTH_001	Invalid credentials	Check email/password
VAUTH_002	Account locked	Contact admin
VAUTH_003	Sub-user disabled	Contact owner
VAUTH_004	Till not assigned	Contact manager
VAUTH_005	Session expired	Re-login

Related Files

File	Purpose
lib/screens/auth/vendor_login_screen.dart	Vendor login
lib/screens/auth/subuser_login_screen.dart	Sub-user login
lib/screens/auth/set_password_screen.dart	Set password
lib/screens/auth/otp_screen.dart	OTP screen
lib/controllers/auth_controller.dart	Auth controller
lib/providers/permission_provider.dart	Permission provider
lib/services/auth_service.dart	Auth service