QR Code authentication is the primary login method in Loyalty.lt, enabling secure authentication between desktop/web and mobile applications using real-time communication.
Overview
QR Code authentication allows users to securely log in to desktop or web applications by scanning a QR code with their mobile device. This method provides enhanced security and convenience.Authentication Flow
1
Generate QR Code Session
Desktop/web application generates a unique QR code session
2
Display QR Code
QR code is displayed to user on desktop/web interface
3
User Scans QR Code
Authenticated user scans QR code using mobile app
4
User Confirms Login
User confirms login on mobile device
5
Receive Authentication
Desktop/web receives authentication tokens via real-time notification
Endpoints
Generate QR Login Session
POST /{locale}/shop/auth/qr-login/generate
Parameters:
Language locale code (en, lt, etc.)
Name of the device generating the QR session (max 255 characters)
Unique session identifier for tracking QR login process
QR code string to be encoded and displayed to user
Session expiration timestamp (5 minutes from creation)
Poll QR Login Status
GET /{locale}/shop/auth/qr-login/poll/{sessionId}
Parameters:
Language locale code
The session ID from generate QR endpoint
Session identifier
Current session status:
pending
, scanned
, or confirmed
Session expiration timestamp
Scan QR Code (Mobile App)
This endpoint requires the user to be authenticated via mobile app with valid JWT token.
POST /{locale}/shop/auth/qr-login/scan/{qrCode}
Parameters:
Language locale code
QR code string from the generated session
Bearer JWT token of authenticated mobile user
Session identifier that was scanned
Name of the device requesting authentication
Confirm QR Login (Mobile App)
POST /{locale}/shop/auth/qr-login/confirm/{sessionId}
Parameters:
Language locale code
Session ID from the scanned QR code
Bearer JWT token of authenticated mobile user
Real-time Communication
The QR login system uses Ably for real-time communication to notify the desktop/web application when authentication status changes.
WebSocket Channel
Subscribe to:qr-login:{sessionId}
Event Types
Payload when scanned:Payload when confirmed:
Implementation Example
Security Features
Session Expiration
Session Expiration
- QR sessions automatically expire after 5 minutes
- Expired sessions cannot be scanned or confirmed
- Real-time status updates stop when session expires
User Authorization
User Authorization
Secure Token Generation
Secure Token Generation
- JWT tokens generated specifically for QR login
- Refresh tokens provided for token renewal
- Tokens transmitted via secure real-time channel
Real-time Security
Real-time Security
- Uses Ably for secure WebSocket communication
- Session-specific channels prevent cross-session access
- Authentication data only sent on successful confirmation
Error Handling
Error Code | Description | Resolution |
---|---|---|
VALIDATION_ERROR | Invalid request parameters | Check device_name length |
QR_SESSION_NOT_FOUND | Session expired or doesn’t exist | Generate new QR session |
AUTH_REQUIRED | Mobile user not authenticated | Login to mobile app first |
QR_CODE_NOT_FOUND | QR code expired or invalid | Generate new QR code |
QR_SESSION_UNAUTHORIZED | User not authorized for session | Use same account that scanned QR |
QR_GENERATION_ERROR | Failed to create QR session | Try again or contact support |
QR_SCAN_ERROR | Failed to scan QR code | Check network and try again |
QR_CONFIRM_ERROR | Failed to confirm login | Check authentication and retry |