Flinks Standard Integration (Flinks Connect + API)

The Flinks integration flow, incorporating the mandatory Authorize Token and the API Secret (x-api-key), is structured as a secure, multi-step process involving both front-end user authentication via Flinks Connect and back-end data retrieval via Flinks API aggregation endpoints.

When both the Authorize Token and API Secret security features are enabled, the integration requires continuous generation and usage of the Authorize Token across the entire session initiation process.

1. Credential Prerequisites

The integration relies on four primary API security credentials, that will be provided to you:

1. Flinks Auth Key (flinks-auth-key): This is the credential used to generate the temporary Authorize Token.

2. API Secret (x-api-key): This credential is used to access Aggregation and Attributes endpoints (e.g., /GetAccountsDetail).

3. CustomerId: To be used in the API endpoints and is meant to identify your instance (environment).

4. Instance name: To be used in both Flinks Connect and API endpoints and it's an additional identifier of your instance (environment).

2. Front-End Integration: Flinks Connect (Authentication)

Flinks Connect is the customizable iFrame interface that manages the user interaction, including selecting the financial institution, providing credentials, and handling Multi-Factor Authentication (MFA).

Step 1: Generate the Authorize Token (for Front-End)

The Authorize Token is mandatory for all new Flinks Connect integrations as of October 2024.

• Your server must call the /GenerateAuthorizeToken API endpoint using the flinks-auth-key credential.

• The output of this call is the single-use Authorize Token.

Step 2: Launch Flinks Connect

• The generated Authorize Token must be included as a parameter (authorizeToken) within the Flinks Connect iframe URL.

• The customer completes the authentication process (consent, institution selection, login, MFA) within the Flinks Connect iframe.

Step 3: Retrieve the LoginId

Upon successful completion of the flow, Flinks Connect returns a non-expiring unique identifier called the loginId.

• The loginId is typically retrieved from the pre-configured redirect URL (redirectUrl) or via a JavaScript Event Listener that captures the REDIRECT step.

• The loginId must be securely stored by your server, as it is required for all future data access requests related to that connected account.

3. Back-End Integration: API Endpoints (Data Retrieval)

Once the loginId is stored, the back-end sequence is used to initiate a session and retrieve the cached financial data (Aggregation data).

Step 4: Generate a New Authorize Token (for Back-End)

The /Authorize endpoint requires a valid Authorize Token when this security feature is enabled.

• Your server must execute a second call to the /GenerateAuthorizeToken endpoint using the flinks-auth-key credential to acquire a fresh, valid token for the API session initiation.

Step 5: Initiate the Session (/Authorize in Cached Mode)

This step exchanges the stored loginId for a temporary requestId (which validates the session).

• You call the /Authorize endpoint using a POST method.

• The request must include the saved loginId and the parameter MostRecentCached:true to signal that you are retrieving the latest saved information.

• Crucially, this API call must also pass the newly generated Authorize Token as an input parameter.

• A successful call returns an HTTP status code 200 and a requestId. This requestId is valid for 30 minutes for aggregation endpoints.

Step 6: Request Data (/GetAccountsDetail)

Using the unique requestId obtained in the previous step, you call the aggregation endpoint to retrieve the financial data.

• You call the /GetAccountsDetail endpoint (or /GetAccountsSummary) using a POST method that includes the requestId.

• This is the stage where the API Secret (x-api-key) is required, typically passed in the request headers, to authenticate the retrieval of the aggregated data payload.

Step 7: Handle Asynchronous Retrieval (Polling)

If the requested data is still being processed in the background (which is common, especially if Flinks Connect just finished processing data), the API will respond asynchronously.

• The API returns an HTTP status code 202 OPERATION_PENDING.

• Your server must poll the asynchronous endpoint, /GetAccountsDetailAsync (a GET request), using the requestId until a successful HTTP 200 response is received. Polling should generally occur every 10 seconds for a maximum of 30 minutes.

This rigorous security flow ensures that communication with the front-end (Flinks Connect) and the back-end API functions (/Authorize) are continuously authenticated using dynamically generated Authorize Tokens, while the final step of data retrieval is protected by the persistent API Secret (x-api-key).