Quick Start
Set up and test two-factor authentication in Payload CMS.
Quick Start
This guide walks you through enabling two-factor authentication for a user and testing the complete login flow.
Complete the Installation guide before continuing.
Before You Begin
Make sure:
- Payload 2FA is installed and configured.
- Your Payload application is running.
- Your authentication collection contains at least one user.
- You can already log in to the Payload Admin Panel.
- You have a TOTP-compatible authenticator application.
Enable 2FA
Sign in to the Payload Admin Panel using an existing user.
Open your user document in the configured authentication collection and locate the Two-Factor Authentication section.
Select Enable 2FA.
Scan the QR Code
Payload 2FA generates a QR code for the account.
Open your authenticator application and scan the QR code.
You can use applications such as:
- Google Authenticator
- Microsoft Authenticator
- Authy
- 1Password
- Other TOTP-compatible applications
Verify the Setup
Your authenticator application will generate a six-digit code.
Enter the code and select Verify Code.
After successful verification, two-factor authentication is enabled for the account.
Save Your Backup Codes
Payload 2FA generates backup codes when 2FA is enabled.
Backup codes are shown only when they are generated. Store them somewhere secure before leaving the page.
Backup codes can be used instead of an authenticator code if the authenticator application is unavailable.
Test the Login
Log out of the Payload Admin Panel.
Sign in again using the same account.
Because 2FA is enabled, the login flow now requires an additional verification code.
Enter the code generated by your authenticator application.
After successful verification, you will be redirected to the Payload Admin Panel.
Test a Backup Code
Log out again and start the login process.
When prompted for the two-factor authentication code, enter one of your backup codes instead.
A valid backup code should complete authentication successfully.
Existing Payload Applications
For an existing Payload CMS application, the setup process is the same.
Use the authentication collection configured during installation and enable 2FA for an existing user.
If your application uses a custom authentication collection, Payload 2FA uses that collection automatically based on your plugin configuration.
Verify the Setup
At this point, verify these three scenarios:
2FA Disabled
A user without 2FA enabled can continue to log in normally.
2FA Enabled
A user with 2FA enabled must complete the additional verification step.
Backup Code
A valid unused backup code can be used instead of an authenticator code.
If these authentication flows work as expected, your Payload 2FA setup is complete.
Last updated on