Prepare recovery before enrollment
TOTP adds a second check to an account; it does not replace secure password storage, session invalidation, rate limits, or a verified recovery process. Complete signup, verification, sign-in, password recovery, and administrative recovery from the authentication guide first.
Enroll and confirm in one controlled session
- Sign in as the ordinary user who will own the second factor.
- Start the TOTP enrollment action exposed by the active release.
- Show the returned secret or QR representation once, over TLS, and do not write it to application logs.
- Add it to the authenticator and submit a current code to confirm enrollment.
- Require confirmation before treating the factor as active.
Resolve exact action names and payload fields from the running server’s OpenAPI/metadata because they are part of the release contract. Do not invent client-side enrollment state.
Verify success and refusal paths
- A current unused code completes the intended sign-in or confirmation flow.
- An incorrect code is rejected without revealing whether another factor was correct.
- An expired or replayed code is rejected according to the deployed release’s window.
- Repeated failures are rate-limited and observable without recording the code.
- Password reset or factor recovery has the documented effect on existing sessions.
Make recovery narrower than normal sign-in
Recovery should require a separately verified channel or an administrator procedure with audit evidence. Never let knowledge of the password alone silently remove the second factor. Notify the account owner when a factor is added, removed, or recovered, and retest access from an older session after the change.