Request 2FA
Setup two-factor authentication with authenticator app, email, or SMS for enhanced account security
2FA SETUP
Request 2FA
Initiate two-factor authentication setup using authenticator apps, email verification, or SMS codes for enhanced account protection.
Account Verification Required
Email must be verified before setting up 2FA. Complete email verification first if you haven't already.
Overview
The request2FA mutation initiates the two-factor authentication setup process. Users can choose between three methods: authenticator app (Google Authenticator, Authy), email codes, or SMS codes. This endpoint generates the necessary credentials for the chosen method.
GraphQL Schema
mutation {
request2FA(
email: String!
method: String!
phone: String
): String!
}Parameters
String
User's verified email address. Account must already be verified before 2FA setup.
method
RequiredString
2FA method: app, email, or phone
phone
OptionalString
Phone number with country code (e.g., "+14155551234"). Required only when method is phone.
2FA Methods
appAuthenticator App
Returns a QR code image that can be scanned with Google Authenticator, Authy, or similar TOTP apps.
Most secure option with offline code generation
emailEmail Code
Sends a 6-digit verification code to the registered email address for each login attempt.
Convenient option using existing email account
phoneSMS Code
Sends a 6-digit verification code via SMS to the provided phone number for each login.
Requires valid phone number with SMS capability
Return Values
Returns a base64-encoded QR code image string when method is app
data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...
Sent verify code via emailConfirmation that a 6-digit verification code has been sent to the registered email address.
Sent verify code via SMSConfirmation that a 6-digit verification code has been sent via SMS to the provided phone number.
Not verifiedEmail account is not verified. User must complete email verification before setting up 2FA.
Example Usage
Authenticator App Setup
mutation Setup2FA_App {
request2FA(
email: "demouser@nyyu.io"
method: "app"
)
}Response:
{
"data": {
"request2FA": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAAAB5fY51..."
}
}QR Code Received
Display the QR code image for the user to scan with their authenticator app. Then call confirmRequest2FA with the code from the app.
Email Code Setup
mutation Setup2FA_Email {
request2FA(
email: "demouser@nyyu.io"
method: "email"
)
}Response:
{
"data": {
"request2FA": "Sent verify code via email"
}
}Check Email
A 6-digit verification code has been sent to demouser@nyyu.io. Use this code to confirm 2FA setup.
SMS Code Setup
mutation Setup2FA_Phone {
request2FA(
email: "demouser@nyyu.io"
method: "phone"
phone: "+14155551234"
)
}Response:
{
"data": {
"request2FA": "Sent verify code via SMS"
}
}Check SMS
A 6-digit verification code has been sent to +14155551234. Use this code to confirm 2FA setup.
Error: Unverified Account
{
"errors": [
{
"message": "Not verified"
}
]
}Email Verification Required
Complete email verification before setting up 2FA. Check your inbox for the verification code.
2FA Setup Flow
Complete 2FA Configuration Process
🔐
Step 1: Choose Method
User selects preferred 2FA method: authenticator app, email, or SMS
📲
Step 2: Receive Credentials
System sends QR code (app) or verification code (email/SMS)
mutation request2FA(email, method, phone?)✅
Step 3: Confirm Setup
User enters verification code to confirm 2FA is working correctly
→ confirmRequest2FA(email, method, code)Implementation Example
Frontend Integration
// Example: 2FA setup handler with multiple methods
async function handleRequest2FA(email, method, phone = null) {
try {
const result = await graphqlClient.mutate({
mutation: gql`
mutation Request2FA($email: String!, $method: String!, $phone: String) {
request2FA(email: $email, method: $method, phone: $phone)
}
`,
variables: {
email: email,
method: method,
phone: phone
}
});
const response = result.data.request2FA;
if (method === "app") {
// Display QR code for authenticator app
const qrCodeImage = response; // base64 image string
displayQRCode(qrCodeImage);
showNotification(
"Scan this QR code with your authenticator app (Google Authenticator, Authy, etc.)"
);
} else if (method === "email") {
// Email code sent
showNotification("A verification code has been sent to your email.");
showCodeInputDialog();
} else if (method === "phone") {
// SMS code sent
showNotification(`A verification code has been sent to ${phone}`);
showCodeInputDialog();
}
// Move to confirmation step
setState({
twoFAMethod: method,
awaitingConfirmation: true
});
} catch (error) {
if (error.message.includes("Not verified")) {
showError("Please verify your email before setting up 2FA.");
router.push('/verify-email');
} else if (error.message.includes("Cannot find user")) {
showError("Email not found. Please sign up first.");
router.push('/signup');
} else {
console.error("2FA request failed:", error);
showError("Failed to setup 2FA. Please try again.");
}
}
}
// Display QR code for app method
function displayQRCode(base64Image) {
const qrCodeElement = document.getElementById('qr-code');
qrCodeElement.src = base64Image;
qrCodeElement.style.display = 'block';
// Also provide manual entry option
const secret = extractSecretFromQR(base64Image);
document.getElementById('manual-secret').textContent = secret;
}
// Method selector component
function TwoFAMethodSelector({ onSelect }) {
return (
<div className="grid gap-4 md:grid-cols-3">
<button onClick={() => onSelect('app')} className="method-card">
<span className="text-4xl">📱</span>
<h3>Authenticator App</h3>
<p>Most secure option</p>
<span className="badge">Recommended</span>
</button>
<button onClick={() => onSelect('email')} className="method-card">
<span className="text-4xl">📧</span>
<h3>Email Code</h3>
<p>Convenient and reliable</p>
</button>
<button onClick={() => onSelect('phone')} className="method-card">
<span className="text-4xl">💬</span>
<h3>SMS Code</h3>
<p>Requires phone number</p>
</button>
</div>
);
}Use Cases
Initial 2FA Setup
New users setting up 2FA for the first time during account registration process
Method Change
Existing users switching from one 2FA method to another (e.g., email to app)
Additional Methods
Users adding backup 2FA methods for redundancy and account recovery
Security Enhancement
Users upgrading from less secure methods (email/SMS) to authenticator app
Best Practices
📱 Recommend App Method
Suggest authenticator apps as the most secure option with offline code generation and no dependency on email/SMS delivery
🔐 QR Code Display
When showing QR codes, also provide manual entry option (secret key text) for users who can't scan the code
📞 Phone Validation
Validate phone numbers client-side and require international format (+country code) before submission
⚡ Clear Instructions
Provide step-by-step instructions for each method, especially for first-time users unfamiliar with 2FA
✅ Multiple Methods
Allow users to configure multiple 2FA methods as backup options in case primary method is unavailable
🎯 Next Steps
Immediately guide users to confirmation step after successful request - don't leave them wondering what to do next
Authenticator App Recommendations
Compatible Authenticator Applications
Google Authenticator
Official Google 2FA app with cloud backup
Authy
Multi-device sync with cloud backup
Microsoft Authenticator
Microsoft's official authenticator app