The /user/mfa API calls

Multi-factor Authentication (MFA) calls on a user object allow you to authenticate the user.

Seting Up A New MFA Factor

  1. Create a factor using /user/mfa/create.
  2. Send initial challenge using /user/mfa/send_challenge.
  3. Confirm the code and get a trusted device cookie using /user/mfa/confirm.

Testing and Confirming A Device

  1. Test the trusted device cookie using /user/mfa/validate_cookie.
  2. Challenge with the default factor using /user/mfa/send_default_challenge.
  3. Confirm the code and get a trusted device cookie using /user/mfa/confirm.

Managing Factors

  1. List all MFA factors using /user/mfa/find.
  2. Delete a factor (can only be done at wepay.com for security purposes).

Version: v2 2017-02-01

POST Endpoint

https://wepayapi.com/v2/user/mfa

/user/mfa/create

Use this call to begin to initiate the process of registering a new MFA Factor for a user.

Tip

For security purposes, if this user already has MFA established, platforms must include a valid trusted device cookie as part of the call. If necessary, platforms will need to have the user go through a challenge and confirm sequence to get a trusted device cookie. It is not necessary for the device to be trusted for 30 days, just to have a valid cookie.

Most partners will create the first MFA factor for a user so this step won’t be required. If no default exists, and this factor is not type backup, then it becomes the default on creation. Adding subsequent methods does NOT automatically make them the new default. Use /user/mfa/modify if you want to offer that option to users.

Arguments

Parameter Required Type Description
type Yes String (2083 chars) The type of authentication factor to be created.

Possible values: voice, sms, authenticator, and backup.
nickname No String (2083 chars) WePay will generate a nickname if one is not supplied.
setup_data No International Phone Number Structure Required if type is voice or sms.
cookie No String (2083 chars) Required if the user already has one or more MFA factors.

Example

{
   "type": "sms",
   "nickname": "Ryan's iPhone 6",
   "setup_data": {
      "country_code": "+1",
      "phone_number": "2025550142"
   },
   "cookie": "WSIG=Ap4P... .GTEq; Domain=foo.com; Path=/; Expires=Wed, 13 Jan 2015 22:23:01 GMT; Secure; HttpOnly"
}

Response

Response Type Description
mfa_id Integer (64 bits) The unique integer MFA ID for a new MFA factor.
state String (2083 chars) The returned state will always be new if type is not backup, otherwise it will be confirmed.
type String (2083 chars)

The type of authentication message.

Possible values: voice, sms, authenticator, and backup.

nickname String (2083 chars) The nickname that was passed in or generated.
factor_label String (2083 chars) A string that is safe to display to users for this factor.
challenge_data Challenge Data Structure Depends on type. If type is sms or voice, then phone_number is returned. If type is authenticator, then qr is returned. If type is backup, then backup_codes is returned.

Example

{
   "mfa_id": 123456789,
   "state": "new",
   "type": "sms",
   "nickname": "Ryan's iPhone 6",
   "factor_label": "SMS: Phone number ending in 26.",
   "challenge_data": {
      "phone_number": "12025550142"
   }
}

Arguments

Parameter Required Type Description
mfa_id Yes Integer (64 bits) The unique ID of the new MFA factor.
cookie Yes String (2083 chars) Trusted device cookie retrieved from user's browser. If not available, pass an empty string.

Example

{
   "mfa_id": 123456789,
   "cookie": "WSIG=Ap4... .GTEq; Domain=foo.com; Path=/; Expires=Wed, 13 Jan 2015 22:23:01 GMT; Secure; HttpOnly"
}

Response

Response Type Description
challenge_required Boolean Indicates whether or not the cookie is valid. If false the cookie is valid. If the cookie is invalid, the call will fail. For more information, see MFA error code 7102.

Example

{
   "challenge_required": false
}

/user/mfa/send_challenge

Use this call to send a code to the user if the challenge type is sms or voice. This call does nothing if the challenge type is authenticator or backup.

Arguments

Parameter Required Type Description
mfa_id Yes Integer (64 bits) The unique ID for the MFA factor.
force_voice No Boolean SMS is the default method of sending an authentication code (challenge). Set this optional parameter to true to force the challenge to be sent as a voice call.

Default: false

Example

{
   "mfa_id": 123456789,
   "force_voice": false
}

Response

Response Type Description
mfa_id Integer (64 bits) The ID for the MFA factor.
state String (2083 chars) Indicates whether or not the target device has been confirmed. If not confirmed, the state will be new, otherwise the state will be confirmed.
type String (2083 chars) The method by which the challenge is delivered to the user. Possible values: voice, sms, authenticator, and backup.
nickname String (2083 chars) The nickname that the user gave for this factor.
factor_label String (2083 chars) A string that is safe to display to users for this factor.

Example

{
   "mfa_id": 123456789,
   "state": "confirmed",
   "type": "sms",
   "nickname": "Ryan's iPhone 6",
   "factor_label": "SMS: Phone number ending in 26."
}

/user/mfa/send_default_challenge

Use this call to send a code to the user if the challenge type is sms or voice. Does nothing if the challenge type is authenticator or backup. The send_default_challenge call takes no arguments and its response is the same as the send_challenge call.

Arguments

This call has no arguments.

Response

Response Type Description
mfa_id Integer (64 bits) The ID for the MFA factor.
state String (2083 chars) Indicates whether or not the target device has been confirmed. If not confirmed, the state will be new, otherwise the state will be confirmed.
type String (2083 chars) The method by which the challenge is delivered to the user. Possible values: voice, sms, authenticator, and backup.
nickname String (2083 chars) The nickname that the user gave for this factor.
factor_label String (2083 chars) A string that is safe to display to users for this factor.

Example

{
   "mfa_id": 123456789,
   "state": "confirmed",
   "type": "sms",
   "nickname": "Ryan's iPhone 6",
   "factor_label": "SMS: Phone number ending in 26."
}

/user/mfa/confirm

Use this call to confirm that the user’s token is valid and accepted. Provides a trusted device cookie that the app can store in the user’s browser on success.

Arguments

Parameter Required Type Description
mfa_id Yes Integer (64 bits) The unique ID for the MFA factor
challenge Yes MFA Challenge Structure Information specific to the MFA.

Example

{
   "mfa_id": 123456789,
   "challenge": {
      "code": "456789",
      "keep_session": true,
      "cookie_domain": ".example.com"
   }
}

Response

Response Type Description
mfa_id Integer (64 bits) The ID for the MFA factor.
state String (2083 chars) Indicates that the user's token was successfully confirmed. The value will always be confirmed. If the token was not successfully confirmed (HTTP code 400), the api will return an error.
type String (2083 chars) The method by which the challenge was issued.

Possible values: voice, sms, authenticator, and backup.
nickname String (2083 chars) The nickname that the user gave for this factor.
factor_label String (2083 chars) A string that is safe to display to users for this factor.
cookie String (2083 chars) The trusted device cookie to be set in the user's browser.

Example

{
   "mfa_id": 123456789,
   "state": "confirmed",
   "type": "sms",
   "nickname": "Ryan's iPhone 6",
   "factor_label": "SMS: Phone number ending in 26.",
   "cookie": {
      "signature": "WSIG=be7148d34ebccdc6423b19085378aa0bee970bdc61d144bd1a8c48c33079ab09; Domain=.gofundme.com; Path=/; Expires=Wed, 13 Jan 2021 22:23:01 GMT; Secure; HttpOnly"
   }
}

/user/mfa/find

Use this call to return an array of structures of all registered MFA factors for a specified user. There are no required arguments for this call. The user’s access token passed in the auth header is all that is required.

Arguments

Parameter Required Type Description
challenge No String (2083 chars) This optional parameter allows you to filter on the type of MFA challenge issued to the user specified in the authentication header. If this paramater is not specified, the api returns all factors.

Possible values: sms, voice, authenticator, and backup.

Example

{
    "challenge": "sms"
}

Response

Response Type Description
mfa Array of MFA Find Response Structures. Information for a matching MFA factor.

Example

Note: This example corresponds to a call with no challenge argument specfied. If the challenge argument was specified as sms, then only objects of type sms are returned.

[
   {
      "mfa_id": 983500482,
      "state": "confirmed",
      "type": "sms",
      "factor_label": "Phone Number Ending in 7183 (SMS)",
      "nickname": "My SMS phone number"
   },
   {
      "mfa_id": 1516366769,
      "state": "confirmed",
      "type": "authenticator",
      "factor_label": "Google Authenticator",
      "nickname": "My Google authenticator"
   }
]

/user/mfa/modify

Make an MFA factor the default.

Arguments

Parameter Required Type Description
mfa_id Yes Integer (64 bits) The ID of the specific MFA factor that is the new default.

Example

{
   "mfa_id": 123456789
}

Response

Response Type Description
mfa_id Integer (64 bits) The ID for the MFA factor
state String (2083 chars) The returned state will always be new if type is not backup, otherwise it will be confirmed.
type String (2083 chars) The type of authentication message.

Possible values: voice, sms, authenticator, and backup.
nickname String (2083 chars) The nickname that the user gave for this factor.
factor_label String (2083 chars) A string that is safe to display to users for this factor.

Example

{
   "mfa_id": 123456789,
   "state": "confirmed",
   "type": "sms",
   "nickname": "Ryan's iPhone 6",
   "factor_label": "SMS: Phone number ending in 26."
}

/user/mfa/reset

Reset all MFA devices for a user.

Arguments

Parameter Required Type Description
old_phone Yes International Phone Number Structure A phone number for a user's existing confirmed MFA device.
security_questions_answered Yes Boolean Must be set to true, this is an acknowledgement by your application that the user has successfully answered security questions as a means to verify their identity.
original_ip Yes String A valid IPv4 or IPv6 address of the user making the reset request.

Example

{
   "old_phone": {
      "country_code": "1",
      "phone_number": "5006007000"
   },
   "security_questions_answered": true,
   "original_ip": "1.2.3.4"
}

Response

A successful reset returns an empty array.

Example

[]