MFA Setup Operations

This section documents the GraphQL mutations used for setting up, modifying, and managing Multi-Factor Authentication methods.

mfaSetupRequest

Initiates the MFA setup process for a user who hasn't previously enabled MFA.

Request

# For authenticator app
mutation {
  mfaSetupRequest(input: { type: AUTHENTICATOR }) {
    status
    message
    userId
    email
    otpAuthUrl
    otpAuthKey
  }
}

# For phone-based MFA
mutation {
  mfaSetupRequest(
    input: { type: PHONE, phoneNumber: "5551234567", phoneCode: "+1" }
  ) {
    status
    message
    userId
    email
    phone
  }
}

Input Fields

Field	Type	Description	Required
type	MfaType	"PHONE" or "AUTHENTICATOR"	Yes
phoneNumber	String	Phone number (for PHONE type)	Only for PHONE type
phoneCode	String	Country phone code (for PHONE type)	Only for PHONE type

Authentication

• Requires authentication via accessToken

Response

// For authenticator app
{
  "data": {
    "mfaSetupRequest": {
      "status": "SUCCESS",
      "message": "MFA setup initiated",
      "userId": "60a2e7e3b...",
      "email": "j***@example.com",
      "otpAuthUrl": "otpauth://totp/BlockBet:j***@example.com?secret=AAABBBCCC&issuer=BlockBet",
      "otpAuthKey": "AAABBBCCC"
    }
  }
}

// For phone-based MFA
{
  "data": {
    "mfaSetupRequest": {
      "status": "SUCCESS",
      "message": "Verification code sent",
      "userId": "60a2e7e3b...",
      "email": "j***@example.com",
      "phone": "+1***1234"
    }
  }
}

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
phone	String	Partially masked phone number (for phone-based MFA)
otpAuthUrl	String	URL for configuring authenticator apps (for authenticator-based MFA)
otpAuthKey	String	Secret key for manual configuration of authenticator apps

mfaSetupVerify

Verifies and completes the MFA setup process by confirming the user can correctly generate or receive verification codes.

Request

mutation {
  mfaSetupVerify(
    input: {
      type: AUTHENTICATOR # or PHONE
      code: "123456"
    }
  ) {
    status
    message
  }
}

Input Fields

Field	Type	Description	Required
type	MfaType	"PHONE" or "AUTHENTICATOR"	Yes
code	String	Verification code received or generated	Yes

Authentication

• Requires authentication via accessToken

Response

{
  "data": {
    "mfaSetupVerify": {
      "status": "SUCCESS",
      "message": "MFA setup successful"
    }
  }
}

mfaEditRequest

Initiates the process to modify an existing MFA method.

Request

# Same structure as mfaSetupRequest
mutation {
  mfaEditRequest(
    input: { type: PHONE, phoneNumber: "5557654321", phoneCode: "+1" }
  ) {
    status
    message
    userId
    email
    phone
  }
}

Authentication

• Requires authentication via accessToken
• Requires USER role
• Requires user to be verified

Response

• Same structure as mfaSetupRequest response

mfaEditVerify

Verifies and completes the MFA edit process.

Request

# Same structure as mfaSetupVerify
mutation {
  mfaEditVerify(input: { type: PHONE, code: "123456" }) {
    status
    message
  }
}

Authentication

• Requires authentication via accessToken
• Requires USER role
• Requires user to be verified

Response

• Same structure as mfaSetupVerify response

disableMfa

Disables MFA for the user completely.

Request

mutation {
  disableMfa {
    status
    message
  }
}

Authentication

• Requires authentication via accessToken
• Requires USER role
• Requires user to be verified

Response

{
  "data": {
    "disableMfa": {
      "status": "SUCCESS",
      "message": "MFA disabled successfully"
    }
  }
}

editMfaRequirements

Configures when MFA verification is required during platform usage.

Request

mutation {
  editMfaRequirements(
    input: { deviceRemoval: true, withdrawal: true, login: false }
  ) {
    status
    message
  }
}

Input Fields

Field	Type	Description	Required
deviceRemoval	Boolean	Require MFA for device removal	Yes
withdrawal	Boolean	Require MFA for withdrawals	Yes
login	Boolean	Require MFA for login	Yes

Authentication

• Requires authentication via accessToken

Response

{
  "data": {
    "editMfaRequirements": {
      "status": "SUCCESS",
      "message": "MFA requirements updated successfully"
    }
  }
}

Common Errors

• "MFA_ALREADY_ENABLED" - When trying to set up MFA for a user who already has it enabled
• "INVALID_PHONE_NUMBER" - Phone number format is invalid
• "INVALID_PHONE_CODE" - Country phone code is invalid
• "MFA_TYPE_NOT_SUPPORTED" - Unsupported MFA type requested
• "WRONG_2FA_CODE" - Verification code doesn't match the expected value
• "USER_MFA_LOCKED" - User's MFA verification is temporarily locked due to too many failed attempts
• "AUTHENTICATOR_ALREADY_INITIALIZED" - When trying to set up authenticator for a user who already has it initialized