Realtime MFA Workflow

Some MFA challenges will be time-sensitive and must be answered within a certain window before they expire. We call these “realtime” for short. They represent a slightly different MFA scenario than other challenges due to their time-sensitivity. This section covers two of the most common realtime MFA challenges. Note that if you do not resolve realtime MFA questions within the time limit, the status will return “resync” and you will have to restart the MFA process by re-initiating a sync.

Sending Users a PIN Code

One common realtime MFA is the case where an institution sends a user a PIN via email or text, which must be passed back within a certain time frame. For this type of challenge, the challenges object in the /sync endpoint has two parts. First, it will act like a choices MFA because the user must choose where he or she wants the PIN sent (phone number, email, etc). Second, it will act like a question MFA, because the user must pass through the correct PIN code once they’ve received it. When a sync hits the first stage of a realtime MFA, it will look like a choices MFA, as discussed in a previous section. Note that at this point, expires will be “(null)” because the act of choosing where you want a PIN code to be sent isn’t time sensitive (entering the code after you’ve received the pin is, however). Here is an example response body below:

        {
            "challenges": [
                {
                    "connection_id": 4224865,
                    "choices": [
                        {
                            "category": "Voice",
                            "key": 0,
                            "value": "xxx-xxx-0695"
                        },
                        {
                            "category": "Text",
                            "key": 1,
                            "value": "xxx-xxx-0695"
                        },
                        {
                            "category": "Voice",
                            "key": 2,
                            "value": "xxx-xxx-5309"
                        },
                        {
                            "category": "Text",
                            "key": 3,
                            "value": "xxx-xxx-5309"
                        }
                    ],
                    "expires": null,
                    "id": 1669462,
                    "question": "Where should we send your pin?",
                    "should_answer": true,
                    "type": "question",
                }
            ]
        }

From the challenges object, you can prompt your users to choose one of the choices passed back to answer the question. Once your user has made their choice, make a POST /sync request and pass the answer back through along with the challenge_id .

curl -X POST \
    -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
    -H "Content-Type: application/json" \
    -d '{"answers": [{"challenge_id": 1669462, "answer": 1}]}' \
    "https://api.quovo.com/v3/connections/4224865/sync"

After passing back the option the user chose, make a GET /sync request and continue to monitor the status , until you see “question.” This MFA question is the one that needs to be answered within a certain time period. This time, the challenges object indicates this is realtime by having a value for when the PIN expires . The response body will also include information about the question you need to answer and if you should_answer it. You will know this is a realtime. Here is a sample response body below:

        {
            "challenges": [
                {
                    "connection_id": 4224865,
                    "expires": "2018-01-28T13:02:10Z",
                    "id": 1669462,
                    "question": "Enter your pin:",
                    "should_answer": true,
                    "type": "question",
                }
            ]
        }

From the challenges object, you can see your user needs to answer a free form question . Once your user has passed their answer to you, make a POST /sync request and pass the answer back through along with the challenge_id before the expires time.

curl -X POST \
    -H "Authorization: Bearer a724809d37d0a21b7e9257f45cee416f5aec61993ab4b09e" \
    -H "Content-Type: application/json" \
    -d '{"answers": [{"challenge_id": 1669466, "answer": "1234"}]}' \
    "https://api.quovo.com/v3/connections/1669462/sync"

CAPTCHA

CAPTCHA challenges also require that the user pass through what they see in the image within a certain time frame. Unlike PIN codes, a CAPTCHA challenge is one step: you will see a value in the expires field in the challenge object.

The challenge object will also include an image , which is the CAPTCHA visual, and a prompt indicating the user should enter the value of the CAPTCHA, where you should pass through users’ attempts to input what they see in the CAPTCHA image. Once your user has passed their answer to you, make a POST /sync request and pass the answer back through along with the challenge_id before the expires time. Remember that if the MFA expires, the status of this connection will go to “resync.”

Go to top

Next: User Config Workflow