NYYU Logo
APIRegistration

Confirm 2FA Setting

Verify and activate two-factor authentication configuration with confirmation code

2FA CONFIRMATION

Confirm 2FA Setting

Verify and activate two-factor authentication by confirming the setup with a valid verification code.

Final Setup Step

This is the last step in 2FA configuration. After confirmation, 2FA will be active and required for all future logins.

Overview

The confirmRequest2FA mutation verifies that the 2FA method was properly configured by validating the verification code provided by the user. This confirms that the user can successfully generate or receive 2FA codes before activating the requirement.


GraphQL Schema

mutation {
  confirmRequest2FA(
    email: String!
    method: String!
    code: String!
  ): String!
}

Parameters

email

Required

String

User's verified email address that is setting up 2FA.

method

Required

String

2FA method being confirmed: app, email, or phone

code

Required

String

6-digit verification code from authenticator app, email, or SMS.


Return Values

Success

2FA setup confirmed successfully. The selected method is now active and will be required for all future sign-ins.

Failed

Verification code is incorrect or expired. User should request a new code or verify they entered it correctly.


Error Responses

⚠️Cannot find user by {email}

Email address is not registered in the system.

📧

Your account is not verified

Email must be verified before 2FA can be configured. Complete email verification first.

🔧There is no proper 2FA setting

No pending 2FA setup found. User must call request2FA first to initiate setup.


Example Usage

Confirm Authenticator App

mutation Confirm2FA_App {
  confirmRequest2FA(email: "demouser@nyyu.io", method: "app", code: "123456")
}

Response:

{
  "data": {
    "confirmRequest2FA": "Success"
  }
}

2FA Activated

Authenticator app 2FA is now active. You'll need to enter a code from your app on every sign-in.

Confirm Email Method

mutation Confirm2FA_Email {
  confirmRequest2FA(email: "demouser@nyyu.io", method: "email", code: "550880")
}

Response:

{
  "data": {
    "confirmRequest2FA": "Success"
  }
}

Email 2FA Active

Email-based 2FA is now enabled. You'll receive a code via email for each sign-in attempt.

Confirm SMS Method

mutation Confirm2FA_Phone {
  confirmRequest2FA(email: "demouser@nyyu.io", method: "phone", code: "789012")
}

Response:

{
  "data": {
    "confirmRequest2FA": "Success"
  }
}

SMS 2FA Active

SMS-based 2FA is now enabled. You'll receive a code via text message for each sign-in.

Failed Confirmation

{
  "data": {
    "confirmRequest2FA": "Failed"
  }
}

Invalid Code

The verification code is incorrect or has expired. Please check the code and try again, or request a new one.


Confirmation Flow

2FA Confirmation Process

📲

Step 1: Receive Code

After calling request2FA, user receives QR code (app) or verification code (email/SMS)

QR scanEmail codeSMS code

🔢

Step 2: Generate/Enter Code

User generates code from app or receives it via email/SMS, then enters it

6-digit verification code

Step 3: Confirm Setup

System validates code and activates 2FA for the account

mutation confirmRequest2FA(email, method, code)

🔐

Step 4: 2FA Active

2FA is now required for all future sign-ins to enhance account security

Enhanced securityRequired on login

Implementation Example

Frontend Integration

// Example: Confirm 2FA setup handler
async function handleConfirm2FA(email, method, code) {
  try {
    const result = await graphqlClient.mutate({
      mutation: gql`
        mutation ConfirmRequest2FA(
          $email: String!
          $method: String!
          $code: String!
        ) {
          confirmRequest2FA(email: $email, method: $method, code: $code)
        }
      `,
      variables: {
        email: email,
        method: method,
        code: code,
      },
    });

    const response = result.data.confirmRequest2FA;

    if (response === "Success") {
      // 2FA successfully activated
      showSuccess(`2FA via ${method} is now active!`);

      // Store 2FA status
      localStorage.setItem("2fa_enabled", "true");
      localStorage.setItem("2fa_method", method);

      // Redirect to next step (e.g., avatar setup or dashboard)
      router.push("/setup-avatar");
    } else if (response === "Failed") {
      // Invalid or expired code
      showError("Invalid verification code. Please try again.");

      // Optionally offer to resend code
      showResendOption();
    }
  } catch (error) {
    if (error.message.includes("Your account is not verified")) {
      showError("Please verify your email first.");
      router.push("/verify-email");
    } else if (error.message.includes("There is no proper 2FA setting")) {
      showError("No 2FA setup in progress. Please start setup first.");
      router.push("/setup-2fa");
    } else if (error.message.includes("Cannot find user")) {
      showError("Account not found.");
      router.push("/signup");
    } else {
      console.error("2FA confirmation failed:", error);
      showError("Failed to confirm 2FA. Please try again.");
    }
  }
}

// Code input validation
function validateCode(code) {
  // Must be exactly 6 digits
  return /^\d{6}$/.test(code);
}

// Auto-submit when 6 digits entered
function handleCodeInput(value, email, method) {
  if (validateCode(value)) {
    // Auto-submit when code is complete
    handleConfirm2FA(email, method, value);
  }
}

// Resend code option
function showResendOption() {
  showDialog({
    title: "Invalid Code",
    message: "The code you entered is incorrect or has expired.",
    actions: [
      {
        label: "Try Again",
        onClick: () => clearCodeInput(),
      },
      {
        label: "Get New Code",
        onClick: () => handleRequest2FA(email, method),
      },
    ],
  });
}

Use Cases

🔐

First-Time Setup

New users completing initial 2FA configuration during account registration

🔄

Method Verification

Confirming that new 2FA method works before disabling old method

Backup Method

Adding additional 2FA methods as backup options for account recovery

🛡️

Security Upgrade

Switching from less secure to more secure 2FA method (email → app)


Best Practices

🔢 Auto-Submit

Automatically submit the form when user enters 6 digits for seamless UX

⏱️ Code Expiration

Display countdown timer for email/SMS codes and offer easy resend option

✅ Clear Feedback

Provide immediate visual feedback for success/failure with clear next steps

🔄 Error Handling

Offer to resend code or restart setup process if confirmation fails multiple times

💾 Save Backup Codes

After successful 2FA setup, provide backup recovery codes for account access if 2FA method is lost

📱 Test Before Activation

Explain that this confirmation ensures 2FA works before making it required for login


Security Notes

🔒
Important Security Considerations
Protect user accounts during 2FA setup

Immediate Activation: 2FA becomes required immediately after confirmation to prevent security gaps

Backup Methods: Encourage users to set up multiple 2FA methods for account recovery

Recovery Codes: Generate and display one-time recovery codes after successful 2FA setup

Rate Limiting: Limit confirmation attempts to prevent brute force attacks on verification codes