Appearance
Two-Factor Authentication
EaseLab supports time-based one-time passwords (TOTP) compatible with Google Authenticator, Microsoft Authenticator, Authy, and similar apps. Recovery codes provide backup access when the authenticator is unavailable.
Who should enable 2FA?
| Role | Recommendation |
|---|---|
| Tenant owner | Required for production labs |
| Lab administrators | Strongly recommended |
| Reception / technicians | Optional; enable for shared workstations |
| Platform admins | Strongly recommended |
Enabling 2FA
Authenticated users manage 2FA under Account Settings or via the API:
| Step | Endpoint | Description |
|---|---|---|
| 1. Check status | GET /me/2fa | Returns enabled and recovery code count |
| 2. Start setup | POST /me/2fa/setup | Returns QR code URI and shared secret |
| 3. Confirm | POST /me/2fa/enable | Body: { "code": "123456" } — returns recovery codes |
| 4. Disable | POST /me/2fa/disable | Requires current TOTP or recovery code |
WARNING
Store recovery codes securely. They are shown once during setup and cannot be retrieved later without disabling and re-enabling 2FA.
Login with 2FA
When 2FA is enabled, POST /auth/login returns:
json
{ "requiresTwoFactor": true, "userId": "..." }Complete sign-in with POST /auth/verify-2fa:
| Field | Required | Notes |
|---|---|---|
userId | Yes | From login response |
code | Yes* | 6-digit TOTP code |
recoveryCode | Yes* | Alternative to TOTP |
*Provide either code or recoveryCode, not both.
On success, access and refresh tokens are issued the same as a normal login.
Recovery codes
- Generated when 2FA is first enabled.
- Each code is single-use.
- Using a recovery code does not disable 2FA.
- If all codes are lost, a tenant admin or platform operator must assist with account recovery.
Platform admin 2FA
Platform admin accounts support the same TOTP flow. Platform admin user records expose twoFactorEnabled in the admin user list.
Security properties
| Property | Detail |
|---|---|
| Algorithm | TOTP (RFC 6238) |
| Window | Standard time step with clock skew tolerance |
| Brute-force protection | Auth endpoints are rate-limited |
| Session binding | 2FA challenge is tied to userId from initial login |
Troubleshooting
| Symptom | Solution |
|---|---|
| Code always invalid | Check device time sync (NTP) |
| Lost phone | Use a recovery code |
| Lost phone and codes | Contact platform support or tenant admin |
| 2FA loop on login | Clear cookies; ensure correct portal URL |
See Troubleshooting: Login for more access issues.