Reauthorisation Guide

The Partners API Re-authorisation guide will put you through the necessary steps to take when trying to successfully reauthorise an account that has MFA (Multi-factor Authorisation) enabled or not.

Integration Stages

With the above prerequisite steps already taken, please note that there are several stages for completing the integration process:

Step 1: Reauth Session

This step is used to reauthorise a previously linked user's account.
When to use: If a user's account access has expired or requires re-authentication, initiate a reauth session to start the process.

Step 2: Reauth Login

This step is used for some connections that require the user to login again or that require MFA.
When to use: If the institution requires the user to re-enter credentials or complete MFA, use this step after starting a reauth session.

Reauth Session

To create a reauth session, you need to pass the account ID. Once the session is successfully created, we’ll send the mono.events.account_reauthorized webhook, followed by the mono.events.account_updated webhook to notify you that new data is available.

Request

curl -X POST "https://api.withmono.com/v2/connect/reauth/session" \
  -H "mono-sec-key: <your_secret_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "<account_id>"
  }'

Parameter Description:

• account (required): The unique identifier of the user's account you wish to reauthorize.

Response

{
    "status": "successful",
    "message": "Request completed successfully",
    "timestamp": "2025-05-13T12:26:36.853Z",
    "data": {
        "responseCode": 99,
        "code": "code_q90t4ar2uriet5ey4rs22v0x"
    }
}

Post-Login Flow and Response Code Handling

After a login attempt, the connection may require additional steps such as further input or account selection. To help you manage this flow effectively, a "responseCode" will be returned to indicate the next action required.

Response code values and their meaning:

See also:

• Webhooks documentation for handling asynchronous events
• Error handling guide for troubleshooting response codes

Reauth Login

Some connections may require re-login or multi-factor authentication (MFA). In such cases, use the endpoint below to initiate re-authentication using the same session ID from the previously created reauth session.

Request Body Parameter

• username (required): The user's account identifier (usually their email or account number) that you intend to log-in to.
• password (required): The user's password for the financial institution.

Request Headers

Include the following header in your request for authentication:

• mono-sec-key (required): Your Mono secret key.
• x-session-id (required): The session ID returned from the reauth session step.

Request

curl -X POST "https://api.withmono.com/v2/connect/reauth/login" \
  -H "mono-sec-key: <your_secret_key>" \
  -H "x-session-id: <reauth_session_id>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "samuel@neem.com",
    "password": "pass1234567890?"
  }'

Parameter Description:

• username: The user's account identifier (email or account number).
• password: The user's password for the financial institution.

Response

{
    "status": "successful",
    "message": "Request completed successfully",
    "timestamp": "2025-05-13T12:26:02.404Z",
    "data": {
        "responseCode": 99,
        "code": "code_geiyk72og91xl2rox16b4emc"
    }
}