Documentation Menu
TOTP Setup
Add Google Authenticator as a second factor for wallet access.
What is TOTP?
TOTP stands for Time-based One-Time Password. It generates a 6-digit code that changes every 30 seconds. The code is produced by an authenticator app on your phone — such as Google Authenticator, Authy, or Microsoft Authenticator.
In W2QR, TOTP serves as an additional verification layer when accessing your wallet. It is especially useful when unlocking your wallet on a new or borrowed device where you have not registered biometrics. Even if someone knows your password, they cannot unlock your wallet without the 6-digit code from your authenticator app.
Setup flow
- Open Security Settings and find the Authenticator section.
- Click Set Up Authenticator. The server generates a TOTP secret and displays it as a QR code on screen.
- Open Google Authenticator (or your preferred authenticator app) on your phone and scan the QR code to add the W2QR account.
- Enter the 6-digit code currently shown in the authenticator app. This confirms the secret was transferred correctly and completes enrollment.
Once verified, TOTP is enabled. It will be required when unlocking on devices without registered biometrics.
How TOTP integrates with unlock
On a registered device (one with stored biometrics), unlock with your password and biometric verification (fingerprint or Face ID). No TOTP needed.
On a new device (no registered biometrics), enter your password and then the 6-digit TOTP code for server-side verification.
Both factors are required — password alone is not sufficient on a device with biometric or TOTP protection enabled.
Reset and replacement
If you lose access to your authenticator app (lost phone, reinstalled app, factory reset), you can reset TOTP through one of these recovery paths:
- •Registered device biometric — use a device where you already set up fingerprint or Face ID. The biometric proves your identity and authorizes the TOTP reset.
- •Google Account sign-in — sign in with your Google Account to prove ownership and authorize the TOTP reset.
After resetting, you must enroll a new authenticator from scratch. The old TOTP secret is permanently invalidated — even if you still have the old authenticator app entry, its codes will no longer work.
Security
Server-side only. The TOTP secret is generated and stored exclusively on the server. It is encrypted using W2QR’s key management system — KEK envelope encryption via HKDF-SHA-256. The secret is never included in the QR code and never sent to the client in any form. Your authenticator app receives the secret once during setup via the on-screen QR code; after that, only the 6-digit verification codes cross the network.
Rate-limited. TOTP verification is limited to 3 attempts per 30-second window. After 5 consecutive failures, the account enters a 5-minute lockout period. This makes online brute-force attacks against the 6-digit code impractical.
Audit-logged. All TOTP verification attempts — successful and failed — are recorded in the security audit log with timestamps and IP addresses.
Generic errors. The server never reveals whether a w2qrId exists, whether TOTP is enrolled for a given wallet, or whether the submitted code was close to correct. All error responses are identical to prevent information leakage.
Not in the QR. Because the TOTP secret lives only on the server, stealing the QR code does not give an attacker access to the TOTP factor. They would still need to compromise your authenticator app or one of the recovery paths.