Intro to MFA

This guide explains how to deal with multi-factor authentication (MFA) while running an aggregation-type process. This guide assumes you’ve already read our Getting Started with API Endpoints guide and our Aggregating with API Endpoints guide. It begins after you have checked the connection status again and received a connection_status of CHALLENGED.

To revisit, if you’ve been prompted for MFA, you’ve completed the following steps already:

1. Checked the member’s connection status
2. Called the aggregate member endpoint

This guide starts at the third step and checks the member’s status again, receives a CHALLENGED connection status, and continues to resolve MFA.

1. Challenged Connection Statuses

When checking the connection_status again, make a GET request to the read member status endpoint as shown.

Endpoint:

GET /users/{user_guid}/members/{member_guid}/status

Notice in the example response that the connection status is CHALLENGED and there is a new array returned in this response called challenges. This indicates that the aggregation has run into multi-factor authentication, and the status response 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?.

1
2
3
curl -i 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa/status' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-u 'client_id:api_key'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
  "member": {
    "aggregated_at": "2020-09-21T19:48:57Z",
    "challenges": [
      {
        "field_name": null,
        "guid": "CRD-8f841084-66cb-4e3d-9253-96f97093100a",
        "label": "What city were you born in?",
        "type": 0
      }
    ],
    "connection_status": "CHALLENGED",
    "guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
    "is_authenticated": false,
    "is_being_aggregated": true,
    "successfully_aggregated_at": "2020-09-21T19:44:17Z"
  }
}

2. Answering Challenges with the Resume Endpoint

The resume aggregation endpoint allows you to answer the challenges presented during MFA and continue the aggregation 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 aggregation endpoint twice: once to choose the phone number and again to provide the correct code. Also, use the read member status endpoint multiple times to get two different challenge GUIDs, one for the phone number and one for the code.

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.

Endpoint:

PUT /users/{user_guid}/members/{member_guid}/resume

1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl -i -X PUT 'https://int-api.mx.com/users/USR-11141024-90b3-1bce-cac9-c06ced52ab4c/members/MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa/resume' \
-u 'client_id:api_key' \
-H 'Accept: application/vnd.mx.api.v1+json' \
-H 'Content-Type: application/json' \
-d '{
      "member": {
        "challenges": [
          {
            "guid": "CRD-8f841084-66cb-4e3d-9253-96f97093100a",
            "value": "correct"
          }
        ]
      }
    }'

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "member": {
    "aggregated_at": "2020-09-21T19:48:57Z",
    "connection_status": "RESUMED",
    "guid": "MBR-84ca0882-ad6c-4f10-817f-c8c0de7424fa",
    "id": null,
    "institution_code": "mxbank",
    "is_being_aggregated": true,
    "metadata": null,
    "name": "MX Bank",
    "successfully_aggregated_at": "2020-09-21T19:44:17Z",
    "user_guid": "USR-11141024-90b3-1bce-cac9-c06ced52ab4c"
  }
}`

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 aggregation 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.