MFA Verification Operations

This section documents the GraphQL mutations used for verifying user identity using Multi-Factor Authentication during login and sensitive operations.

mfaRequest

Initiates the MFA verification process by requesting a verification code to be sent to the user's registered MFA method.

Request

mutation {
  mfaRequest {
    status
    message
    userId
    email
    phoneNumber
    phoneCode
    nextRequestAt
  }
}

Authentication

• Requires authentication via accessToken
• Used during login with valid mfaAccessToken

Response

{
  "data": {
    "mfaRequest": {
      "status": "SUCCESS",
      "message": "Verification code sent successfully",
      "userId": "60a2e7e3b...",
      "email": "j***@example.com",
      "phoneNumber": "***1234",
      "phoneCode": "+1",
      "nextRequestAt": 1625076245
    }
  }
}

Response Fields

Field	Type	Description
status	String	"SUCCESS" or "ERROR"
message	String	Human-readable message about the result
userId	String	User ID
email	String	Partially masked email address
phoneNumber	String	Partially masked phone number (for phone-based MFA)
phoneCode	String	Phone country code (for phone-based MFA)
nextRequestAt	Int	Unix timestamp when next MFA request can be made

Possible Errors

• "MFA_NOT_ENABLED" - User doesn't have MFA enabled
• "NO_REQUEST_NEEDED_FOR_AUTHENTICATOR" - Authenticator-based MFA doesn't require a request
• "RATE_LIMIT_EXCEEDED" - Too many attempts, try again later

mfaVerify

Verifies the MFA code provided by the user during login or sensitive operations.

Request

mutation {
  mfaVerify(
    input: { code: "123456", fingerprint: "device-fingerprint-hash-value" }
  ) {
    status
    message
  }
}

Input Fields

Field	Type	Description	Required
code	String	Verification code from SMS or authenticator app	Yes
fingerprint	String	Device fingerprint for session tracking	Yes

Authentication

• Uses OptionalGuard to allow verification via mfaAccessToken or existing session
• Can be called with mfaAccessToken cookie during login process

Response

{
  "data": {
    "mfaVerify": {
      "status": "SUCCESS",
      "message": "MFA verification successful"
    }
  }
}

Response Fields

Field	Type	Description
status	String	"SUCCESS" or "ERROR"
message	String	Human-readable message about the result

Possible Errors

• "INVALID_CODE" - The provided verification code is incorrect
• "CODE_EXPIRED" - The verification code has expired
• "INVALID_REQUEST" - Missing required authentication
• "TOO_MANY_ATTEMPTS" - Too many failed verification attempts
• "WRONG_2FA_CODE" - Incorrect verification code
• "USER_MFA_LOCKED" - User's MFA verification is temporarily locked due to too many failed attempts

Side Effects

Upon successful verification:

1. The server sets the accessToken and refreshToken cookies
2. The session is established for the given fingerprint
3. The mfaAccessToken cookie is cleared

Example Workflow

1. User completes initial login with username/password
2. System responds with mfaAccessToken cookie and requires MFA verification
3. User makes mfaRequest mutation to request a verification code
4. User receives code via SMS or generates it with authenticator app
5. User makes mfaVerify mutation with the code and device fingerprint
6. Upon success, user receives full authentication cookies and proceeds to application