Dealing with Multifactor Authentication
This guide explains how to deal with multifactor authentication (MFA) while running an aggregation-type job. If you've been prompted for MFA, you've completed the following steps already:
- Called the tax docs endpoint.
- Checked the member's connection status:
GET /users/{user_guid}/members/{member_guid}/status.
MFA is indicated when you see a connection_status of CHALLENGED. You'll also see an array returned in this response called challenges which includes the specific question or questions the end user will need to answer to proceed.
Make a note of both the guid in the challenges array and the label, in this case, What city were you born in?.
Here is an example:
_18{_18 "member": {_18 "aggregated_at": "2020-09-21T19:48:57Z",_18 "challenges": [_18 {_18 "field_name": null,_18 "guid": "CRD-8f841084-66cb-4e3d-9253-96f97093100a",_18 "label": "What city were you born in?",_18 "type": 0_18 }_18 ],_18 "connection_status": "CHALLENGED",_18 "guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",_18 "is_authenticated": false,_18 "is_being_aggregated": true,_18 "successfully_aggregated_at": "2020-09-21T19:44:17Z"_18 }_18}
Use the Resume Endpoint
The PUT /users/{user_guid}/members/{member_guid}/resume endpoint allows you to answer the challenges presented during MFA and continue the tax docs process. There are also other forms of MFA, such as choosing from multiple options (like choosing from a list of phone numbers to text a code to) or choosing the correct pre-determined photo. These are not covered in this guide, but they are possible scenarios with the MX API.
A relatively common scenario is requiring a one-time code texted to a phone number. In this case, use the resume endpoint twice: once to choose the phone number and again to provide the correct code. Also, use the connection status endpoint multiple times to get two different challenge GUIDs: one for the phone number and one for the code.
In this guide, we're using MX Bank test institution. To mimic a successful answer, use correct as the value.
In an actual MFA situation, the end user will need to provide the correct answer to the question. If the security question is What city were you born in?, the answer may be Chicago, Tallahassee, etc.
In the body of the request, include the challenge guid provided in the previous response and the correct answer to the question given in the label field of the last response.
Notice that connection_status has changed to RESUMED and is_being_aggregated is still true. However, the is_authenticated field is still false. This indicates that the MFA answer provided was correct and the tax docs job is proceeding, but the member's login credentials have not yet been authenticated. Keep checking the status to make sure there are no more challenges or errors.