NYYU Logo
APIRegistration

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

email

Required

String

User's verified email address. Account must already be verified before 2FA setup.

method

Required

String

2FA method: app, email, or phone

phone

Optional

String

Phone number with country code (e.g., "+14155551234"). Required only when method is phone.


2FA Methods

📱app

Authenticator 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

📧email

Email Code

Sends a 6-digit verification code to the registered email address for each login attempt.

Convenient option using existing email account

💬phone

SMS 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

📱Authenticator App Response

Returns a base64-encoded QR code image string when method is app

data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...

📧Sent verify code via email

Confirmation that a 6-digit verification code has been sent to the registered email address.

💬Sent verify code via SMS

Confirmation that a 6-digit verification code has been sent via SMS to the provided phone number.

⚠️Not verified

Email 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

App (most secure)EmailSMS

📲

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

iOSAndroid
🔴

Authy

Multi-device sync with cloud backup

iOSAndroidDesktop
🟣

Microsoft Authenticator

Microsoft's official authenticator app

iOSAndroid