Two-factor authentication and account security

Turn on two-factor sign-in with an authenticator app, keep recovery codes, require 2FA for others, manage sessions and recover access after losing a phone.

Updated Oct 9, 2026 · 7 min read

Two-factor authentication (2FA) asks for a 6-digit code from an app on your phone after your password, so a stolen or guessed password alone cannot open the panel. ZoPanel uses standard TOTP codes, which work with Google Authenticator, Authy, 1Password, Microsoft Authenticator, Bitwarden and other authenticator apps. Every panel user can turn it on: administrators, resellers, customers and website members.

Turn on two-factor authentication

You need an authenticator app on your phone (or a password manager that stores TOTP codes).

Open My account (in the Account menu, or the menu under your name).
In the Two-factor authentication card, enter your Current password and click Enable 2FA.
Scan the QR code with your app. If you cannot scan it, type the Secret key shown below it into the app.
Enter the 6-digit code the app shows in Authentication code and click Verify & enable.
The Recovery codes appear. Click Copy or Download and store them somewhere safe, away from your phone (a password manager or a printed copy). They are shown only now.

The card now shows Enabled. Turning 2FA on signs out your other sessions and revokes your API tokens; create new tokens afterwards if you use them.

The entry in your app is named after the panel (or your provider's panel name) and your username.

Enter your Username and Password and click Sign in.
Enter the 6-digit code from your app and click Verify.

Each code is valid for 30 seconds, and ZoPanel also accepts the codes just before and after it to allow for small clock differences. A code works only once: after a successful sign-in, the same code (or an older one) is refused. If codes are always rejected, check that the phone's time is set automatically.

Recovery codes

You get 10 recovery codes, each in the form xxxxx-xxxxx. Each one replaces an app code once.

Use one: on the code step of the sign-in page, click Lost your phone? Use a recovery code, enter a code (with or without the dash) and click Verify.
See how many are left: the Two-factor authentication card shows {n} recovery codes left. Using a code is recorded in your Activity Log.
Get new ones: enter your Password and, in Code from the app or a recovery code, a current code from the app or an unused recovery code, then click New recovery codes. The old codes stop working at once.

Make new codes when only a few are left, or if you think someone has seen them.

Turn off two-factor authentication

In the Two-factor authentication card, enter your Password and, in Code from the app or a recovery code, a current code from the app or an unused recovery code, and click Disable 2FA. A recovery code used here is used up. Your other sessions are signed out, your API tokens are revoked and your recovery codes are deleted.

While your administrator requires 2FA for your account, a code from the app is refused here (two-factor authentication is required for your account). Only a recovery code turns it off, for a lost phone, and you must then set up 2FA again before you can do anything else in the panel.

Require 2FA for other users (administrators)

Turn on 2FA on your own account first.
Go to Settings → General → Require two-factor authentication.
Choose who must use it, then click Save:

Option	Who must use 2FA
Not required	Nobody (default)
Administrators and resellers	Every administrator and reseller
Everyone	All users, including customers and website members

A user who must use 2FA but has not set it up is taken to My account after signing in, with the banner Your administrator requires two-factor authentication: set it up below to continue. Until they finish, they can only set up 2FA or sign out. The Administrators list marks administrators without 2FA with no 2FA.

Confirmation for sensitive actions

Some changes ask for your password again even though you are signed in, so that a stolen session cookie is not enough:

Action	Asks for
Change password	Current password
Enable 2FA	Current password
New recovery codes	Password and a code from the app or a recovery code
Disable 2FA	Password and a code from the app or a recovery code
Creating an API token	Password, and the authentication code when 2FA is on
Changing an administrator's Login name	Password, and the authentication code when 2FA is on

Five wrong attempts within 15 minutes block these confirmations for 15 minutes, and a further attempt during the block ends the session.

Changing your password signs out all your other sessions and revokes all your API tokens.

Sessions

The Sessions card on My account lists every browser signed in to your account, with its IP address, browser and last activity. The current one is marked this session.

Click the delete icon on a session to sign it out.
Click Sign out everywhere else to end every session except the current one.

A session ends after 12 hours without activity, and in any case 7 days after sign-in. When your provider uses Log in as this account to help you, that session is not listed in your Sessions, it is recorded under the provider's name in the activity log, and your password, 2FA, API tokens, SSH keys and sessions cannot be changed from it.

Throttling: repeated wrong passwords or codes are refused with too many failed attempts, try again later for 15 minutes (5 failures for one username from one address, 10 failures from one address, or 100 failures for one username from all addresses within an hour). fail2ban also bans addresses with many failures at the firewall. See Security.
Activity Log: customers see their sign-ins and account changes under Account → Activity Log, including changes made by their provider.
Alerts for administrators: in Settings → Alerts, the events Login from a new IP (on by default) and Failed panel logins (off by default) send a message by email, Telegram or webhook. See Panel settings.

API tokens

API tokens (zpat_…) let scripts and billing systems call the API without a password. They are created under My account → API tokens and need a Pro license. A token can never change your password or 2FA, create tokens or open the terminal, and creating one asks for your password (and 2FA code). If 2FA is required for the token's owner, the owner must have it set up or the token is refused. See Provisioning API.

Lost your phone

You can move 2FA to a new phone yourself with two unused recovery codes:

Sign in with a recovery code (see above).
Open My account. In the Two-factor authentication card, enter your Password and another unused recovery code in Code from the app or a recovery code, then click Disable 2FA. This also works where your administrator requires 2FA.
Set up 2FA again with the new phone, as in Turn on two-factor authentication, and store the new recovery codes. Where 2FA is required, the panel asks for this right away and allows nothing else until it is done.

If the app is still on another device (a tablet, a password manager), you can use its codes instead of recovery codes.

If you have no recovery codes left:

Customers, resellers and website members: ask your hosting provider to reset your two-factor authentication. It is done on the server by an administrator with root access, with the command below; a reseller passes the request on to the server's administrator.
Administrators with root access to the server: run, as root:

zopanel ctl disable-2fa USERNAME

This turns 2FA off for that user, signs them out everywhere and revokes their API tokens. They sign in with their password and set up 2FA again under My account; if 2FA is required, they are asked to do it right after sign-in.

If the password is lost too, set a new one:

zopanel ctl reset-password USERNAME
# or choose it:
zopanel ctl reset-password USERNAME --password 'New-Long-Passw0rd'

Without --password, a random 16-character password is printed. Sessions and API tokens of the user are revoked. For a hosting account, the SFTP password is not changed by this command; update it from the panel. An administrator or reseller can also set a new password for one of their customers in Accounts → Edit. See Command-line reference.

Troubleshooting

Message or problem	Cause and fix
`invalid authentication code` or `invalid code`	Wrong code, a code already used, or the phone's clock is off. Turn on automatic time on the phone and use the next code.
`too many failed attempts, try again later`	Throttled after repeated failures. Wait 15 minutes.
`invalid password or code`	The password or the code is wrong in a confirmation form.
`current password is incorrect`	The Current password field is wrong.
`two-factor authentication must be set up first (Account page)`	2FA is required for your account; set it up in My account.
`two-factor authentication is required for your account`	You tried to turn 2FA off with a code from the app while it is required. Only a recovery code turns it off then (lost phone).
`enable two-factor authentication on your own account first`	An administrator tried to require 2FA without having it.
`session expired`	The session was idle for 12 hours, reached 7 days, or was signed out from another session. Sign in again.
The QR code does not scan	Type the Secret key into the app (time-based, 6 digits, 30 seconds).
A recovery code is refused	Each code works once; check {n} recovery codes left and use another one.

← Disaster recovery Country blocking →