/Authorize

📘

This is only required for legacy integrations

This is only required if you are using a legacy integration (that does not support OAuth 2.0). If you are using a custom integration that supports OAuth 2.0, see Using a Custom API Integration.

Generating a new requestId

All retrieval of data starts with new session being initiated. For that, you need to generate a new requestId with Flinks by calling /Authorize.

For custom integrations, all credentials handling between Flinks and the Financial Institution is controlled by /Authorize in live mode (when using MostRecentCached:false), and any Multi-Factor Authentication (MFA) prompts needs to also be handled.

📘

Integrating with Flinks Connect?

Integrations that uses Flinks Connect for handling user banking authentication, uses /Authorize in cached mode, by only specifying the parameter "MostRecentCached": "true" and LoginId, as you need to retrieve already processed data. More details can be found here.

When handling a custom integration, a typical /Authorize initial request body would look like this:

{
    "Institution":"FlinksCapital",
    "username": "Greatday",
    "Password": "Everyday",
    "MostRecentCached":false,
    "Save": true
}

Multi-Factor Authentication

Most financial institutions implement Multi-Factor Authentication, which can be prompted after the first credential pair (username and password) is submitted via /Authorize.

Here is an example of a simple MFA prompt response:

{
    "Links": [
        {
            "rel": "Authorization",
            "href": "/Authorize",
            "example": null
        }
    ],
    "HttpStatusCode": 203,
    "SecurityChallenges": [
        {
            "Type": "QuestionAndAnswer",
            "Prompt": "What shape do people like most?"
        }
    ],
    "Institution": "FlinksCapital",
    "RequestId": "9022abc2-8a2e-4b06-a06e-c3e5449c4d10"
}

In order to complete the session opening, the MFA prompt needs to be answered by calling /Authorize, using the new RequestId (session reference), contained in this first response.

Here is the example of the MFA answer request:

{
    "RequestId": "006fd2f3-055b-4ef6-a9fc-c1261cd76ec6",
    "SecurityResponses": {
        "What shape do people like most?": [
            "Triangle"
        ]
    }
}

When Flinks validates with the financial institution that all submitted credentials are valid and no additional information is required, /Authorize will respond with a 200 HTTP status code.

{
    "Links": [
        {
            "rel": "AccountsDetail",
            "href": "/GetAccountsDetail",
            "example": null
        },
        {
            "rel": "AccountsSummary",
            "href": "/GetAccountsSummary",
            "example": null
        },
        {
            "rel": "Statements",
            "href": "/GetStatements",
            "example": null
        }
    ],
    "HttpStatusCode": 200,
    "Login": {
        "Username": "Greatday",
        "IsScheduledRefresh": false,
        "LastRefresh": "2020-04-15T22:46:03.1690585",
        "Type": "Personal",
        "Id": "b0debb48-f9f1-46c6-80a4-08d7dd88d478"
    },
    "Institution": "FlinksCapital",
    "RequestId": "006fd2f3-055b-4ef6-a9fc-c1261cd76ec6"
}

Once this step is reached, it means that your session was successfully opened, and the received RequestId can be used to make calls to other data retrieval endpoints. (/GetAccountDetails, for example).

LoginId

All successfully completed /Authorize step will also return you a LoginId. (which in the last example was b0debb48-f9f1-46c6-80a4-08d7dd88d478)

A LoginId is the reference of the saved connected account, which needs to be kept safe. If in a later moment you would like simply to retrieve the saved data on a particular account, its LoginId needs to be used on a cached call flow. (In a similar way as Flinks Connect integrations retrieve data).

🚧

Keep track of each new LoginId, for a later use, or even for a later deletion of data, since Flinks will retain data indefinitely unless /DeleteCard is used.