Partners API (Reauth)

Overview

This guide will explain how you can handle the re-authorisation flow for a connected user's account without the re-authorisation connect widget. To achieve this, there would be a need to:

1. Get a reauthorisation token via the re-authorisation API.
2. Create connect session with the re-authorisation token.
3. Commit the session if user input is required.

1. Get a reauthorisation token via the re-authorisation API

The first step here is to make an API call to the Reauthorisation API to get the re-authorization token of a financial account by passing in the account id to the URL path params and your secret key in your headers.

curl --request POST \
     --url https://api.withmono.com/accounts/61ea412ae12e1efab122/reauthorise \
     --header 'Accept: application/json' \
     --header 'mono-sec-key: live_sk_hlo2sdqwq17gdfvdw2ef'

Response

{
  "token": "VwxcfeLRZvq1UlD5WiuN"
}

2. Create connect session with the re-authorisation token

In this step, you are to pass the re-auth token generated above to the body request of our Create Session API.
At this point, our connect session will attempt to login in the background.

If login goes through then re-authorisation is not required, else there can be two possible cases that can be needed for re-authorisation, which can either be the password to this account has changed or the user input is required ie - OTP/2fa.

curl --request POST \
     --url https://api.withmono.com/v1/connect/session \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'mono-sec-key: live_sk_hlo2sdqwq17gdfvdw2ef' \
     --data '{"reauth_token":"VwxcfeLRZvq1UlD5WiuN"}'

{
    "status": "successful",
    "message": "Session created successfully",
    "id": "session_nkgCbmtxyz",
    "app": "61e270e2bbe2010771c0dec7",
    "institution": "5f2d08bf60b92e2888287704",
    "auth_method": "internet_banking",
    "expiresAt": 1657265973940,
    "ui": {
        "title": "KudaBank is requesting you to enter your OTP to continue with Quickstart",
        "form": [
            {
                "type": "elements.input",
                "name": "otp",
                "hint": "Enter OTP",
                "contentType": "password",
                "maxLength": 5
            }
        ]
    },
    "reauth": {
        "response_code": 102,
        "message": "KudaBank is requesting you to enter your OTP to continue with Quickstart"
    }
}

3. Commit the session if user input is required

To complete this final step, if the response code returned in the re-auth object is 102, it means that the user input is required to complete this reauthorization flow. What comes next would be to grab the name field of the form object returned above (ui.form.name) in the create connect session above and pass it to the Commit session API to the body request.
N.B Ensure to get the session id from the API response above in step 2 and pass it to your header as x-session-id.

curl --request POST \
     --url https://api.withmono.com/v1/connect/commit \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'x-session-id: session_nkgCbmtxyz' \
     --header 'mono-sec-key: live_sk_hlo2sdqwq17gdfvdw2ef' \
     --data '{"otp":1234}'

{
    "status": 200,
    "responseCode": 99,
    "data": {
        "code": "code_WH5x2kIMz2B7HibEK12b"
    }
}

Once this step is successful, an account_reauthorized webhook event is sent with the account id in the payload.