Support: Clear a User's TOTP by Hand¶
How support removes a user's two-factor authentication (TOTP) when the user cannot do it themselves.
Required access: a role that may change the production core database (see VPN Access; this site has no production MySQL runbook, so use the access you were granted and keep credentials out of tickets), or the internal admin (see Admin Portal).
When this applies¶
- Frozen account after an email-change revert (CH-1463). The owner undid an email change from the link in the alert mail. If the user already had TOTP when the change was requested, the revert keeps it, resets the password and signs every session out, and the confirmation mail says: "Two-factor authentication is still switched on. If you did not set it up yourself, contact support before you try to sign in again: Forgot password alone will not get you in." The user cannot pass the code prompt, and a self-service disable needs a current code, so support is the only way back.
- Any lost authenticator (new phone, deleted app) with no way to produce a code.
1. Verify the owner first¶
Clearing TOTP removes the second factor, so a wrong person here is an account takeover. Do not skip this.
Revert case, all three:
- The request arrives from the restored address (the one named in the revert confirmation mail), not from the address the change pointed to.
- The user can quote something from the revert mail, such as the cancelled address or the approximate time.
- The account's email in the database is the restored address (SELECT it before you change anything).
Plain lost authenticator: the request comes from the account's email, and the user confirms two facts that are not in the mail itself (for example the account name and the domain of one of its sites). There is no written support identity checklist on this site yet. If the checks are unsatisfactory, refuse and say so on the ticket.
2. The change¶
Preferred: in the internal admin, open the user and use Reset two-factor. It clears the secret, revokes the user's
live sessions and logs an event naming the admin. It landed on the admin repo's main on 11 November 2026; confirm it is
deployed to production before relying on it. It does not touch user_totp_attempts, which is harmless (the counter expires on its own).
Fallback by hand, in one transaction, for one user. Replace <USER_ID> with the id; never run it without the WHERE.
START TRANSACTION;
SELECT id, email, (otp_secret <> '') AS totp_on
FROM users WHERE id = <USER_ID>; -- expect 1 row, totp_on = 1
SELECT * FROM user_totp_attempts WHERE user_id = <USER_ID>; -- 0 or 1 row
UPDATE users SET otp_secret = '', updated_at = NOW() WHERE id = <USER_ID>; -- 1 row
DELETE FROM user_totp_attempts WHERE user_id = <USER_ID>; -- 0 or 1 row
SELECT id, email, (otp_secret <> '') AS totp_on
FROM users WHERE id = <USER_ID>; -- expect totp_on = 0
COMMIT; -- ROLLBACK instead if any count or value above is unexpected
users.otp_secret is the only 2FA state: empty string means off (disable writes '', not NULL). Both the legacy
dashboard login and the React dashboard read it, so one update covers both.
What it does not touch¶
The password, API keys, sessions and the account's email. In the revert case the password is already unusable and the sessions already revoked. For a plain lost authenticator, revoke sessions separately if the device may be in someone else's hands (the admin action does this for you).
3. Record it¶
The hand-written SQL writes no audit event. The dashboard's own disable writes event action 52
(EVENT_ACTION_TOTP_DISABLED), but there is no tool that writes it for support. On the user's ticket, record: who
cleared it, when (UTC), which user id, the verification evidence from step 1, and the output of the final SELECT.
The admin action logs event_actions 8 with the acting admin; still note it on the ticket.
4. Tell the user¶
- Revert case: use Forgot password on the sign-in page first, because the revert made the password unusable.
- Sign in, then open the profile page and enrol TOTP again.
- If they did not set up the TOTP themselves, suggest they review the account's users and API keys.
Why there is no button for the user¶
A self-service "I lost my authenticator" clear would let anyone holding the password, or a hijacked mailbox, remove the second factor, which is exactly the situation 2FA exists for. Disable therefore requires a current code, and recovery goes through a person who verifies identity. If volume grows, a support action that records an audit event and revokes sessions is the follow-up; the admin's Reset two-factor is the start of it.