NYYU Logo
APIRegistration

Forgot Password

Request a password reset code via email when users forget their account credentials

PASSWORD RECOVERY

Forgot Password

Initiate the password reset process by requesting a verification code sent to the registered email address.

Step 1 of Password Reset

This is the first step in password recovery. After receiving the code, use the Reset Password endpoint to set a new password.

Overview

The forgotPassword mutation initiates the password reset process by sending a 6-digit verification code to the user's registered email address. This code is required to complete the password reset.


GraphQL Schema

mutation {
  forgotPassword(
    email: String!
  ): String!
}

Parameters

email

Required

String

Email address of the account requiring password reset. Must be a registered email.


Return Values

Success

Password reset code has been successfully sent to the email address. Check inbox for 6-digit code.

failed

Request failed. Email address may not be registered or there was an error processing the request.


Example Usage

Request Password Reset

mutation RequestPasswordReset {
  forgotPassword(
    email: "demouser@nyyu.io"
  )
}

Response:

{
  "data": {
    "forgotPassword": "Success"
  }
}

Check Your Email

A 6-digit password reset code has been sent to demouser@nyyu.io. Use this code with the Reset Password endpoint to set a new password.

Failed Request

{
  "data": {
    "forgotPassword": "failed"
  }
}

Request Failed

Unable to send reset code. Please verify the email address is correct and registered.


Password Reset Flow

Complete Password Recovery Process

🔑

Step 1: Request Reset Code

User enters email address and requests password reset

mutation forgotPassword(email)

📧

Step 2: Receive Code

System sends 6-digit reset code to registered email address

6-digit codeTime-limited

🔐

Step 3: Reset Password

User enters code and new password to complete reset

→ resetPassword(email, code, newPassword)

Implementation Example

Frontend Integration

async function handleForgotPassword(email) {
  try {
    const result = await graphqlClient.mutate({
      mutation: gql`
        mutation ForgotPassword($email: String!) {
          forgotPassword(email: $email)
        }
      `,
      variables: {
        email: email
      }
    });

    const response = result.data.forgotPassword;

    if (response === "Success") {
      // Show success message
      showSuccess("Password reset code sent to your email!");

      // Store email for next step
      sessionStorage.setItem('resetEmail', email);

      // Redirect to reset password page
      router.push('/reset-password');

      // Show instructions
      showInfo("Check your email for the 6-digit reset code. Enter it on the next page along with your new password.");

    } else {
      // Handle failure
      showError("Failed to send reset code. Please check your email and try again.");
    }

  } catch (error) {
    console.error("Forgot password failed:", error);
    showError("An error occurred. Please try again later.");
  }
}

// Email validation before submission
function validateEmail(email) {
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return emailRegex.test(email);
}

Use Cases

🔑

Forgotten Password

User cannot remember their password and needs to reset it to regain access

🔒

Security Breach

User suspects account compromise and wants to immediately change password

🔄

Password Update

Regular password rotation for security best practices

🚫

Locked Out

Multiple failed login attempts and user needs alternative access method


Best Practices

📧 Email Validation

Validate email format client-side before submission to prevent unnecessary requests

⏱️ Rate Limiting

Implement client-side rate limiting to prevent spam requests (e.g., 1 request per minute)

🔐 Privacy Protection

Don't reveal whether email exists in system - always show generic success message for security

📱 Check Spam Folder

Remind users to check spam/junk folder if they don't receive the reset code

🔄 Session Storage

Store email in session storage to pre-fill on reset page and improve UX


Security Features

🔒
Built-in Security Protections
Password reset safeguards

Time-Limited Codes: Reset codes expire after a short period for security

Rate Limiting: Server-side rate limiting prevents brute force attempts

Email Ownership: Code sent only to registered email proves account ownership

One-Time Use: Each reset code can only be used once and becomes invalid after use