Multi-Factor Authentication (MFA) adds an extra layer of security to your Chatwoot account by requiring a second form of verification in addition to your password. This significantly reduces the risk of unauthorized access, even if your password is compromised.

Chatwoot supports Time-based One-Time Password (TOTP) authentication using standard authenticator apps, as well as backup codes for emergency access.

## Prerequisites

Before enabling MFA:

1. MFA must be enabled at the system level by your administrator

2. You need a TOTP-compatible authenticator app such as:

   * Google Authenticator

   * Microsoft Authenticator

   * Authy

   * 1Password

   * Any other TOTP-compatible app

## User Flows

## - Enabling MFA from Profile Page

This flow allows users to enable two-factor authentication for their account.

#### Step-by-Step Process:

1. **Navigate to MFA Settings**

* Log in to your Chatwoot account

* Click on your profile avatar in the bottom-left corner

* Select "Profile Settings"

* Navigate to the "Two-Factor Authentication" tab

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQnMxVXdJPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--d4e8f4c4a55f6389055806126928a2a52c9e33bf/image.png)

1. Start MFA Setup

* Click the "Enable Two-Factor Authentication" button

* The system will generate a unique secret key for your account

  ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRnMxVXdJPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--989e85a137944cc30085efeccb59d0ef6c961526/image.png)

**3. Configure Authenticator App**

* A QR code will be displayed on the screen

* Open your authenticator app and scan the QR code

* Alternatively, manually enter the secret key if you can't scan the QR code

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCS1BUNlFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--1892b8361da8bbe6e1ca58c8926bd358c5142af9/image.png)


**4. Verify Setup**

* Your authenticator app will generate a 6-digit code

* Enter this code in the verification field

* Click "Verify and Enable"

**5. Save Backup Codes**

* Upon successful verification, you'll receive 10 backup codes

* **Important**: Save these codes in a secure location immediately

* Each backup code can only be used once

* Options available:

* Copy all codes to clipboard

* Download as a text file

* Print for physical storage

  ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRTdVNlFZPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--0fdc39005d20ca685f24bba623d4bdfe4e66edf6/image-1.png)

**6. Confirmation**

* MFA is now enabled for your account

* You'll see a status indicator showing "Two-Factor Authentication is Enabled"

  ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTk0yVXdJPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--5f23e2f57f0adacb108340cfd0d0b208a47522cc/image.png)

---

## - Disabling MFA from Profile Page

Users may need to disable MFA when switching devices or authentication methods.

#### Step-by-Step Process:

1. **Navigate to MFA Settings**

* Go to Profile Settings → Two-Factor Authentication

**2.  Initiate Disable Process**

* Click on "Disable Two-Factor Authentication" button

* A confirmation dialog will appear warning about the security implications

**3. Verify Identity**

* Enter your current password

* Enter a valid 6-digit code from your authenticator app (or use a backup code)

* This dual verification ensures only the account owner can disable MFA

**4. Confirm Disable**

* Click "Disable MFA" to confirm

* The system will remove:

* Your OTP secret

* All unused backup codes

* MFA requirement for login

---

### Regenerating Backup Codes

Users should regenerate backup codes if they've been compromised or used up.

#### Step-by-Step Process:

1. **Access Backup Code Management**

* Navigate to Profile Settings → Two-Factor Authentication

* Locate the "Backup Codes" section

**2. Initiate Regeneration**

* Click "Regenerate Backup Codes"

**3. Verify with Authenticator**

* Enter a current 6-digit code from your authenticator app

* This ensures only authorized users can generate new codes

* 

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCTU00VXdJPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--ba7ad7377f2a053f6a8ca4e4a8dadc211297385f/image.png)

**4. Receive New Codes**

* 10 new backup codes will be generated

* All previous backup codes are immediately invalidated

* Save the new codes securely:

* Copy to clipboard

* Download as file

---

### 4. Login Flow with TOTP or Backup Code

The login process when MFA is enabled requires an additional verification step.

#### Step-by-Step Process:

1. **Initial Login**

* Enter your email and password on the login page

* Click "Sign In"

  ![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCQ0U1VXdJPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--0b407a2dc6c31858f317d13edae55f992ab34522/image.png)

**2. MFA Challenge**

* After successful password verification, you'll be prompted for MFA

* The system provides two options:

* Use authenticator app (default)

* Use backup code (alternative)

![](https://app.chatwoot.com/rails/active_storage/blobs/redirect/eyJfcmFpbHMiOnsibWVzc2FnZSI6IkJBaHBCRnM1VXdJPSIsImV4cCI6bnVsbCwicHVyIjoiYmxvYl9pZCJ9fQ==--21ffebc23bd9083d31fd473dc8ad11af4382dbd9/image.png)

3. **Successful Authentication**

* Upon successful verification, you'll be logged into your dashboard

* If using a backup code, it's marked as used and cannot be reused

* Consider regenerating backup codes if you're running low

#