The /user/mfa API calls

Warning

This feature is deprecated.

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

/user/mfa/create
/user/mfa/validate_cookie
/user/mfa/send_challenge
/user/mfa/send_default_challenge
/user/mfa/confirm
/user/mfa/find
/user/mfa/modify
/user/mfa/reset

Setting Up A New MFA Factor

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

Testing and Confirming A Device

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

Managing Factors

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

Version: v2 2017-05-31

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"
    }
}

/user/mfa/validate_cookie

Use this call to check for a valid trusted device cookie. This call can be made at anytime. It should be made before performing any sensitive operations.

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

[

]