Authentication Flow
Understand how Payload 2FA handles authentication and two-factor verification.
Authentication Flow
Payload 2FA extends Payload's authentication flow when two-factor authentication is enabled for a user.
The behavior depends on whether 2FA is enabled for the account.
User Without 2FA
When 2FA is not enabled, the user can authenticate normally with their email address and password.
Enter Credentials
The user enters their email address and password through the normal login flow.
Authenticate
Payload verifies the credentials and completes the login.
Access the Application
The user receives an authenticated session and can access the Payload Admin Panel.
Normal API-based login also continues to work for users who do not have 2FA enabled.
User With 2FA
When 2FA is enabled, entering a valid email address and password is no longer enough to complete authentication.
The user must complete the additional two-factor verification step.
Enter Credentials
The user enters their email address and password through the Payload 2FA login form.
2FA Required
After the credentials are accepted, the login flow checks whether 2FA is enabled for the account.
If it is enabled, the user must complete the second authentication step.
Enter Verification Code
The user enters either:
- A code generated by their authenticator application
- A valid backup code
Verify the Code
Payload 2FA verifies the submitted code.
If the code is valid, the authentication flow continues.
If the code is invalid, authentication is rejected and the user must try again.
Complete Authentication
After successful 2FA verification, the Payload authentication process is completed and the user receives an authenticated session.
API Login Behavior
When 2FA is enabled for a user, direct API-based login does not complete authentication without the required 2FA verification.
Users with 2FA enabled must use the Payload 2FA login flow.
Users who do not have 2FA enabled can continue to use Payload's normal API login flow.
This restriction applies to authentication. Payload's other APIs continue to work normally after a user is authenticated.
Backup Code Authentication
Backup codes can be used instead of an authenticator code when the user cannot access their authenticator application.
Each backup code can only be used once.
After a backup code is successfully used, it is removed from the user's available backup codes.
Store backup codes securely. They can be used to access an account when the authenticator application is unavailable.
Authentication Overview
The complete flow can be summarized as:
2FA Disabled
Email and password are sufficient to complete authentication.
2FA Enabled
Email and password are accepted, but a second authentication step is required.
Verification
The user provides a TOTP code or backup code.
Authentication Complete
After successful verification, the user is authenticated and can access the Payload Admin Panel.
What Happens After Authentication
Once authentication has been completed successfully, the user can use Payload normally.
Payload 2FA does not disable the application's APIs or change the behavior of authenticated requests.
The additional requirement applies specifically to the login process for users with 2FA enabled.
Last updated on