Authenticator two-factor (TOTP)¶

Patcherly supports app-based two-factor authentication (TOTP) using authenticator apps such as Google Authenticator, Microsoft Authenticator, Authy, 1Password, and similar apps.

Where to manage it¶

• Open Profile → Authenticator app settings (/profile/mfa).
• You can enable your own authenticator, verify setup code, and review whether policy requires enrollment.

Enrollment flow¶

1. Open Profile → Authenticator app settings.
2. Click Start authenticator setup.
3. Scan the QR code in your authenticator app, or enter the shown secret manually.
4. Enter the code from your authenticator app and confirm.

After confirmation, your account has active authenticator-based second factor. At the end of setup, recovery codes are generated once: save/download them immediately.

Recovery codes: keep them safe¶

Recovery codes are emergency one-time login codes. Each code can be used only once.

• Save them in a secure password manager (preferred), encrypted vault, or an offline secure location.
• Do not store them in plain text notes, shared chats, or unencrypted screenshots.
• If you use one code, keep track of remaining codes and regenerate when low.
• You can regenerate a fresh set from your MFA/profile security settings after logging in.

Workspace optional policy (workspace owner)¶

The workspace owner is the account that registered the workspace. Personal plans include one seat; Core and Pro include additional seats — invite team members from Profile → Team (see Workspaces and team members).

The workspace owner can enable Offer optional authenticator setup for everyone on the workspace on Profile → Team (workspace optional authenticator policy card at the bottom). This requires a plan with more than one seat — Personal (one seat) shows an upgrade prompt instead.

When enabled, team members signing in to that workspace can enroll from Profile → Account (Authenticator section). This stays optional unless Require TOTP for everyone is turned on or your account requires MFA.

Workspace owners on multi-seat plans can also reset a locked-out team member's authenticator from the same tab when platform policy allows tenant-admin MFA resets.

Forced enrollment¶

You may be forced to enroll on login when:

• Your workspace enables Require TOTP for everyone in the workspace, or
• Patcherly requires authenticator enrollment for your account.

In forced mode, login pauses at an MFA step until setup/verification is complete.

If code verification fails¶

• Verify device time is correct (automatic time sync enabled).
• Use the newest code (codes rotate every ~30 seconds).
• Re-run setup from profile if needed.

If verification fails repeatedly¶

Each sign-in opens a short-lived MFA ticket (typically valid for 10 minutes). The verify page accepts a small number of failed attempts per ticket; once that cap is reached the ticket is invalidated, the page shows "MFA ticket already used; restart sign-in", and you must start from the login page again.

• A successful authenticator code (or a successful recovery code) also makes the ticket single-use — you cannot replay the same ticket from another browser tab.
• If the same login fails repeatedly across attempts, the login throttle kicks in for your account and IP. The dashboard shows a "Too many login attempts. Retry after Xs" message and the API returns 429 with a Retry-After header. See Login throttling for the timing details.
• If you are locked out and need urgent access, open Support from the bottom of the dashboard sidebar (Pro workspaces may include direct email).

Lost authenticator device¶

Use Use recovery code instead on the MFA page if you saved recovery codes.

You can paste your full saved list into the recovery box (one code per line as when you downloaded/copied it, or space- and comma-separated). The dashboard finds each 8-character code (matching the XXXX-YYYY format once punctuation is stripped) and tries them in order. Your first few lines may already be used up if you signed in with recovery before—we keep going until a code still works.

Each recovery code remains single-use on the server: a successful login marks that code as spent.

What if I have no recovery codes either?¶

We don't expose a way to bypass authenticator verification from the web app — that would let anyone who steals your password also disable your second factor. In order of preference:

1. Email password reset. If you still have access to the email address on file, request a password reset. Once you set a new password you can sign in and re-enrol your authenticator — but the second-factor check still applies, so this only helps if you can still produce a code or recovery code at sign-in.
2. Supervised MFA reset. Open Support from the bottom of the dashboard sidebar (Pro workspaces may include direct email). After an identity check (a brief Q&A confirming details only the account owner would know), Patcherly Staff can reset your authenticator so you can re-enrol on next sign-in. This is the standard recovery path.

All recovery codes already used while signed in¶

If you signed in successfully but had zero unused recovery codes left (every code was consumed), the dashboard restricts you to Profile → Authenticator app settings (/profile/mfa) until you regenerate and save a new code list.

• Navigation to other dashboard pages redirects back to MFA security automatically.
• A banner explains that you must regenerate codes (password + current authenticator code).
• Signing out warns you strongly first; if you proceed without regenerating codes, lockout risks are higher if you also lose device access later.

Support can exceptionally perform a supervised reset, pending ID checks on a case by case basis (see Lost authenticator device).

If recovery codes stop working unexpectedly¶

Recovery codes can become invalid after certain security key rotations on Patcherly’s side.

• Try another unused recovery code first.
• If none work, open Support from the bottom of the dashboard sidebar for a supervised reset (if policy allows), then re-enroll your authenticator and generate a new set of recovery codes.