Email Two-Factor Authentication for WHMCS

Add a second layer of login security for your clients, sub-accounts (users) and administrators by emailing a one-time passcode at sign-in. This guide covers installation, licensing, configuration and day-to-day use.

1. Requirements

• WHMCS 8.x or newer
• PHP 8.1+ with the curl and sodium extensions enabled (standard on modern hosting)
• A working outgoing mail configuration in WHMCS (so codes can be emailed)
• Your License Key (sent to you after purchase)

2. Installation

The download contains a modules folder with two modules.

1. Upload the files. Upload the contents of the package into your WHMCS root directory, merging with the existing modules folder. After uploading you should have:

   modules/addons/emailtwofa/
   modules/security/emailotp/

2. Activate the addon. In the admin area go to Configuration (cog icon) → System Settings → Addon Modules (or Apps & Integrations), find Email 2FA, and click Activate. Then click Configure and grant access to the relevant admin role groups.
3. Activate the security module. Go to Configuration → System Settings → Two-Factor Authentication. You will see an Email Two-Factor Authentication tile — click Activate.

3. Activating your license

Until the license is active, the addon is locked — only the License & Help tab is visible and 2FA will not run.

1. Open Addons → Email 2FA (under the Addons menu in the admin navbar).
2. On the License & Help tab, paste your License Key and click Activate License.
3. The status should change to Active and all other tabs appear.

4. Enabling Email 2FA for clients & admins

Once activated, tell WHMCS who may use it:

1. Go to Configuration → System Settings → Two-Factor Authentication.
2. On the Email Two-Factor Authentication tile click Configure.
3. Tick Enable for use by Clients and/or Enable for use by Administrative Users, then Save.

Important: if these boxes are not ticked, your clients will not see any option to turn on 2FA.

5. Configuration options

Open Addons → Email 2FA → Configure. Available settings:

6. Email templates

On the Email Templates tab you can edit the subject and HTML body of the code email per language, then send a test to yourself. Available merge fields:

{$name}   {$code}   {$validity}   {$ip}   {$company}   {$date}   {$logo}   {$antiphishing}

7. Cron setup (recommended)

Add this cron job to automatically purge expired codes and old logs (every 15 minutes is plenty):

*/15 * * * * php -q /home/youruser/public_html/modules/addons/emailtwofa/cron/cleanup.php

Adjust the path to match your WHMCS installation directory. (Cleanup also runs once daily via the standard WHMCS cron.)

8. How clients turn on 2FA

1. The client logs into the client area and opens Hello, Name → Security Settings (or clientarea.php?action=security).
2. Under Two-Factor Authentication they choose Email Two-Factor Authentication and confirm.
3. If backup codes are enabled, they are shown once — the client should save them.
4. From the next login onward, a code is required.

Administrators enable it the same way from their own admin profile → Two-Factor Authentication.

9. Making 2FA mandatory (optional)

To require everyone to set up 2FA, use WHMCS’s built-in option on the same Two-Factor Authentication settings page:

• Force Client Users to enable Two-Factor Authentication on Next Login
• Force Administrative Users to enable Two-Factor Authentication on Next Login

With these on, users must set up a 2FA method (including Email 2FA) before reaching their area.

10. The login experience

After entering username and password, the user sees a verification screen:

• A code is emailed to their account address; they type it and click Login.
• Resend code appears after the cooldown if the email did not arrive.
• Trust this device for N days skips 2FA on that device/IP for the configured period.
• Use a backup code lets them sign in if they cannot access their email.

11. Admin dashboard

• Dashboard — activity stats and a recent-events chart.
• Logs — searchable audit log with CSV export and purge.
• Configure — all settings above.
• Email Templates — edit and test the code email.
• Trusted Devices — view and revoke remembered devices.
• License & Help — license status and this guide.

12. Troubleshooting

Need more help? Contact support or open the knowledgebase. © Hostorigins — Email 2FA for WHMCS.