logo

Realtime

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