> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pterodactyl/panel/llms.txt
> Use this file to discover all available pages before exploring further.

# Two-Factor Authentication

> Set up and manage 2FA for enhanced account security

## 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

<Steps>
  <Step title="Navigate to Security Settings">
    Go to your **Account Settings** and find the **Two-Factor Authentication** section.
  </Step>

  <Step title="Generate Setup Code">
    Click **Enable Two-Factor Authentication**. The system will generate:

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

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

  <Step title="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.
  </Step>

  <Step title="Enter Verification Code">
    Your authenticator app will display a 6-digit code. Enter this code in the verification field.
  </Step>

  <Step title="Confirm Password">
    For security, you'll need to enter your current password to confirm the 2FA setup.
  </Step>

  <Step title="Save Recovery Codes">
    After successful verification, you'll receive **recovery codes**. These are critical for account access if you lose your authenticator device.

    <Warning>
      **Save these recovery codes immediately!** Store them in a secure location. Each code can only be used once.
    </Warning>
  </Step>
</Steps>

## 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

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

  ```json theme={null}
  {
    "object": "recovery_tokens",
    "attributes": {
      "tokens": ["code1", "code2", ...]
    }
  }
  ```
</Note>

## Using Two-Factor Authentication

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

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

<Tip>
  TOTP codes refresh every 30 seconds. If a code doesn't work, wait for the next code to generate.
</Tip>

## Disabling Two-Factor Authentication

If you need to disable 2FA:

<Steps>
  <Step title="Access Security Settings">
    Navigate to your account settings and find the **Two-Factor Authentication** section.
  </Step>

  <Step title="Confirm Password">
    Enter your current password to verify your identity.
  </Step>

  <Step title="Disable 2FA">
    Click **Disable Two-Factor Authentication**.
  </Step>
</Steps>

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

### 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:

```php theme={null}
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

### "Two-factor authentication is already enabled"

If you see this error when trying to enable 2FA, it means 2FA is already active on your account. You must disable it first before setting it up again.

### Code Not Working

* **Time sync**: Ensure your device's time is synchronized
* **Code expired**: TOTP codes change every 30 seconds - try the next code
* **Wrong account**: Verify you're using the correct entry in your authenticator app

### Lost Authenticator Device

Use one of your recovery codes to log in, then:

1. Disable 2FA
2. Set up 2FA again with your new device
3. Save your new recovery codes

## API Endpoint Reference

```http theme={null}
GET  /api/client/account/two-factor    # Get setup credentials
POST /api/client/account/two-factor    # Enable 2FA
DELETE /api/client/account/two-factor  # Disable 2FA
```

For detailed API documentation, see the [Two-Factor API Reference](/api/client/account).