Skip to main content
Multi-factor authentication (MFA) is an electronic authentication method in which a user is granted access to a website or application only after successfully presenting two or more pieces of evidence (or factors) to an authentication mechanism. MFA protects personal data—which may include personal identification or financial assets—from being accessed by an unauthorized third party that may have been able to discover, for example, a single password. This is a method of adding additional security to your account. The first “factor” is your usual password which is standard for any account. The second “factor” is a verification code retrieved from an app on a mobile device or computer.
Why enable MFA?
  • Protects your account even if your password is compromised
  • Adds a second verification step that only you can complete
  • Prevents unauthorized access to your content and settings
  • Industry-standard security practice recommended for all accounts

​
Enabling MFA

To enable your MFA, go to the main settings page of your account by clicking on Settings > General or by clicking this link: https://buttercms.com/settings/

​
Step-by-step setup

Step 1: Click on the ‘here’ link, which will take you to the Account Security page: Security settings link Step 2: Click on the Enable Two-Factor Authentication button: Enable Two-Factor Authentication button Step 3: Click Next: Click Next Step 4: You will now be asked to use an authenticator app (e.g., Microsoft Authenticator or Google Authenticator) to scan the QR code image: QR code for authenticator Or copy the secret code/key if you prefer manual entry: Secret code entry

​
Using an authenticator app

There are two ways you can use an authenticator app:
  1. Browser extension - Add an authenticator extension to your web browser
  2. Mobile app - Use an authenticator app on your smartphone

​
Browser extension method

  1. Go to your browser’s extensions store to find an authenticator app:
  2. Choose a highly-rated, trusted authenticator app that you like. In the example below, we have chosen Authenticator, an extension for Google Chrome.
Authenticator browser extension
  1. Click “Add to Chrome” to add this extension.
  2. In the top-right corner of the Chrome browser, where the extensions are, click the Authenticator icon to open a pop-up panel.
  3. In the pop-up panel, click the icons in the top-right corner to open the screen where you can choose either “Scan QR Code” or “Manual Entry”.
Authenticator scan options
  1. Once the QR code has been scanned successfully, you will see a new record appear in the list of codes in the Authenticator pop-up panel.
  2. Copy and paste the 6-digit code from your authenticator into ButterCMS.

​
Mobile app method

Open the Google Play Store or the App Store and find a highly-rated, trusted authenticator app. Popular options include:
  • Microsoft Authenticator
  • Google Authenticator
  • Authy
  • 1Password

​
Google Authenticator setup

  1. Once downloaded, open the app and click “Begin setup”.
Google Authenticator setup
  1. Click “Scan barcode”.
Scan barcode option
  1. Once the QR code has been scanned successfully, you will see a new record appear in the list of codes.
  2. Copy and paste the 6-digit code from your authenticator into ButterCMS.

​
Microsoft Authenticator setup

  1. Once downloaded, open the app and click “Add account”
Microsoft Authenticator add account
  1. Select “Other”.
Select Other account type
  1. Once the QR code has been scanned successfully, you will see a new record appear in the list of codes under Accounts.
  2. Copy and paste the 6-digit code from your authenticator into ButterCMS.

​
Logging in with MFA

Once MFA is enabled, your login process will include an additional step:
  1. Enter your email and password as usual
  2. Open your authenticator app
  3. Find the ButterCMS entry and note the current 6-digit code
  4. Enter the code in ButterCMS before it expires (codes typically refresh every 30 seconds)
  5. Click Verify to complete your login
The 6-digit code in your authenticator app changes every 30 seconds. If your code is about to expire, wait for the new code to appear before entering it.

​
Disabling MFA

If you need to disable MFA:
  1. Go to Settings > General
  2. Click on the security settings link
  3. Click Disable Two-Factor Authentication
  4. Enter your current MFA code to confirm
  5. MFA will be disabled for your account
Disabling MFA reduces the security of your account. Only disable MFA if absolutely necessary, and re-enable it as soon as possible.

​
Troubleshooting

Contact ButterCMS support at support@buttercms.com or use the in-app chat. Our team can help you regain access to your account after verifying your identity.
Ensure your device’s time is set correctly. Authenticator apps use time-based codes, so if your device’s clock is off, the codes won’t match. Enable automatic time synchronization on your device.
If your organization uses SSO, MFA is typically handled by your identity provider (e.g., Okta, Azure AD). You would configure MFA settings in your SSO provider, not in ButterCMS directly.
Before switching devices:
  1. Add your new phone as a backup authenticator while you still have access to your old phone
  2. Or disable MFA temporarily, switch devices, then re-enable MFA with your new phone

​
Security best practices

Recommended security practices:
  1. Enable MFA for all team members - Especially those with Admin access
  2. Use a reputable authenticator app - Microsoft Authenticator, Google Authenticator, or Authy are all good choices
  3. Keep backup codes safe - Store them in a secure location in case you lose access to your authenticator
  4. Don’t share codes - Your MFA codes should never be shared with anyone
  5. Use a password manager - Combine MFA with strong, unique passwords for maximum security