Authentication Overview
Introduction​
The BankLingo authentication system provides secure access control for both administrators and customers. It supports multiple verification methods including email OTP, SMS OTP, TOTP authenticator apps (Google Authenticator, Microsoft Authenticator, etc.), biometric device login (fingerprint / Face ID), and liveness check (face capture KYC).
Authentication Methods​
1. Password-Based Login​
All users authenticate initially with their email/username and password. After successful password validation, a two-factor authentication (2FA) step is required.
2. Two-Factor Authentication (2FA)​
The system supports three verification methods for 2FA:
| Method | verificationMethodType | Description |
|---|---|---|
| Default | 0 | Uses the user's preferred method (email or SMS) |
| Email OTP | 1 | One-time password sent via email |
| SMS OTP | 2 | One-time password sent via SMS |
| Authenticator App | 3 | TOTP code from authenticator app |
3. Biometric Login​
Once a device is registered, self-service customers can authenticate using only a biometric device token (fingerprint / Face ID) — no password or OTP required. Login is strictly bound to the registered deviceId + deviceToken pair. Attempting to biometric-login from an unregistered device returns status 45 and requires a password-based device switch confirmation.
See Biometric Login for full details.
4. Liveness Check (Face KYC)​
The liveness check flow uses a challenge-response SDK (blink, smile, turn) to verify the user is a real person. The captured face image is stored in Base64 and is retrievable by admins. This is used for KYC onboarding gating — a user must pass liveness before certain features unlock.
See Liveness Check for full details.
Device Identification Headers​
All self-service authentication endpoints consume device context from HTTP request headers (not the body). This enables consistent audit trails and session tracking regardless of the authentication method used.
| Header | Description |
|---|---|
X-App-Channel | Mobile or Web |
X-Device-Id | Unique device UUID |
X-Device-Token | Biometric token (biometric login only) |
X-Client-Platform | Android, iOS, Chrome, Safari, etc. |
X-App-Version | App / web client version |
X-Device-Host | Device hostname |
X-Device-Model | Device model string |
X-Ip-Address | Client IP |
X-App-Build-Number | App build number |
X-App-Package-Name | App package / bundle ID |
| SMS OTP | 2 |
| Authenticator App | 3 |
Authentication Flow​
Standard Login Flow​
Authenticator App Setup Flow​
API Endpoints​
Admin Login​
- Endpoint:
/api/BPMSelfService/commands/SelfAdminLoginCommand - Method: POST
- Purpose: Administrator login with 2FA support
- View Details →
Customer Login​
- Endpoint:
/api/BPMSelfService/commands/SelfLoginCommand - Method: POST
- Purpose: Customer login with 2FA support
- View Details →
OTP Validation​
- Endpoint:
/api/BPMSelfService/commands/ValidateOtpCommand - Method: POST
- Purpose: Validate email/SMS OTP or TOTP codes
- View Details →
Resend OTP​
- Endpoint:
/api/BPMSelfService/commands/ResendOtpCommand - Method: POST
- Purpose: Resend OTP for email/SMS methods
- View Details →
Authenticator Setup​
- Purpose: Complete guide for setting up authenticator apps
- View Details →
Authenticator Login​
- Purpose: Using authenticator apps for login
- View Details →
Refresh Token​
- Purpose: Refresh JWT access tokens
- View Details →
Security Features​
TOTP (Time-based One-Time Password)​
- Standard: RFC 6238
- Algorithm: HMAC-SHA1
- Key Length: 160 bits (20 bytes)
- Code Length: 6 digits
- Time Step: 30 seconds
- Time Window: ±30 seconds (for clock drift tolerance)
Password Security​
- Passwords are hashed using strong cryptographic algorithms
- Password complexity requirements enforced
- Account lockout after multiple failed attempts
JWT Tokens​
- Tokens are signed using secure algorithms
- Short expiration times with refresh token support
- Include claims for user identity, roles, and permissions
Common Response Codes​
| Status Code | Description |
|---|---|
200 | Success |
400 | Bad request (invalid parameters) |
401 | Unauthorized (invalid credentials or token) |
403 | Forbidden (insufficient permissions) |
404 | User not found |
500 | Internal server error |
Best Practices​
For Frontend Developers​
- Always use HTTPS for authentication endpoints
- Store JWT tokens securely (HttpOnly cookies recommended)
- Clear tokens on logout to prevent unauthorized access
- Handle token expiration gracefully with refresh tokens
- Never log sensitive data (passwords, OTPs, tokens)
For Security​
- Implement rate limiting on login endpoints
- Monitor failed login attempts for suspicious activity
- Use strong password policies (minimum length, complexity)
- Enable 2FA for all users when possible
- Regular security audits of authentication logs
For Authenticator Apps​
-
Recommend popular authenticator apps:
- Google Authenticator
- Microsoft Authenticator
- Authy
- LastPass Authenticator
-
Provide backup codes in case user loses access to authenticator
-
Allow account recovery through alternative methods
-
Test time synchronization issues
Testing​
Testing Email/SMS OTP​
- Use test environment with email/SMS capture
- Verify OTP delivery and expiration
- Test resend functionality
- Test rate limiting
Testing Authenticator Apps​
- Test setup flow with QR code scanning
- Verify TOTP code validation
- Test time window tolerance
- Test with multiple authenticator apps
Error Handling​
Common Errors​
| Error | Cause | Solution |
|---|---|---|
| Invalid OTP | Wrong code or expired | Request new OTP |
| Invalid TOTP | Wrong code or time sync issue | Check device time, try again |
| User locked out | Too many failed attempts | Wait for lockout period or contact admin |
| Setup required | Authenticator not configured | Complete setup flow |
Related Documentation​
Support​
For authentication issues or questions:
- Email: support@banklingo.com
- Documentation: https://banklingo.app/docs/developer-documentation
- Technical Support: See Support Portal