Two-Factor Authentication

Overview

Two-Factor Authentication (2FA) adds an extra layer of security to your account by requiring a time-based one-time password (TOTP) in addition to your regular password when logging in. Pterodactyl uses TOTP-based 2FA, which works with authenticator apps like:

Google Authenticator
Authy
Microsoft Authenticator
1Password
Any other TOTP-compatible app

Enabling Two-Factor Authentication

Navigate to Security Settings

Go to your Account Settings and find the Two-Factor Authentication section.

Generate Setup Code

Click Enable Two-Factor Authentication. The system will generate:

A QR code for easy setup
A secret key (for manual entry)

The setup data is generated by TwoFactorSetupService and includes the secret key and QR code URL (see TwoFactorController.php:36-44).

Scan QR Code

Open your authenticator app and scan the QR code displayed on screen.Alternatively, you can manually enter the secret key if your app doesn’t support QR scanning.

Enter Verification Code

Your authenticator app will display a 6-digit code. Enter this code in the verification field.

Confirm Password

For security, you’ll need to enter your current password to confirm the 2FA setup.

Save Recovery Codes

After successful verification, you’ll receive recovery codes. These are critical for account access if you lose your authenticator device.

Save these recovery codes immediately! Store them in a secure location. Each code can only be used once.

Recovery Codes

When you enable 2FA, you’ll receive a set of recovery tokens. These one-time use codes allow you to access your account if you lose access to your authenticator device.

Best Practices for Recovery Codes

Save them immediately - Download or copy them to a secure location
Store securely - Keep them in a password manager or encrypted file
One-time use - Each code can only be used once
Backup location - Store a copy in a separate secure location

Recovery tokens are returned as a JSON response with the structure:

{
  "object": "recovery_tokens",
  "attributes": {
    "tokens": ["code1", "code2", ...]
  }
}

Using Two-Factor Authentication

Once enabled, you’ll need to provide a 6-digit code from your authenticator app every time you log in:

Enter your email and password as usual
When prompted, open your authenticator app
Enter the current 6-digit code
Complete login

TOTP codes refresh every 30 seconds. If a code doesn’t work, wait for the next code to generate.

Disabling Two-Factor Authentication

If you need to disable 2FA:

Access Security Settings

Navigate to your account settings and find the Two-Factor Authentication section.

Confirm Password

Enter your current password to verify your identity.

Disable 2FA

Click Disable Two-Factor Authentication.

Security Warning: Disabling 2FA reduces your account security. Only disable it if absolutely necessary, and consider re-enabling it as soon as possible.

What Happens When You Disable 2FA

Your TOTP secret is cleared from the system
All recovery codes become invalid
The use_totp flag is set to false
The action is logged as user:two-factor.delete

See TwoFactorController.php:83-100 for implementation details.

Security Features

Password Verification

Both enabling and disabling 2FA require password verification to prevent unauthorized changes:

if (!password_verify($data['password'], $request->user()->password)) {
    throw new BadRequestHttpException('The password provided was not valid.');
}

Activity Logging

All 2FA changes are logged:

Enable 2FA: user:two-factor.create
Disable 2FA: user:two-factor.delete

You can review these events in your activity feed.

Code Validation

The system validates TOTP codes with:

6-digit requirement - Codes must be exactly 6 digits
Time-based validation - Codes are valid for a short time window
One-time use - Each code can only be used once during its validity period

Troubleshooting