> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flinks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Standard Integration (Widget + API)

> Walk through the standard Flinks integration end to end: launch Flinks Connect on the front end, then authorize and retrieve account data through API requests on the back end.

The **standard integration** is the most common way to connect with Flinks. It pairs the [Flinks Connect](./flinks-connect/flinks-connect) iframe on the front end with **API requests** on the back end. This page walks through the full happy-path flow, from launching the iframe to retrieving account data.

## Front end vs. back end

Every Flinks integration has two independent halves. You choose one option for each.

* **Front end:** what the end user interacts with to connect their account, either the [Flinks Connect](./flinks-connect/flinks-connect) iframe or [Flinks Express](./flinks-express). See [Choose a Front-End Solution](./choose-a-frontend-solution).
* **Back end:** how your system receives the connected data, either API requests or Webhooks. See [Choose a Back-End Solution](./choose-a-backend-solution).

The [Client Dashboard](./getting-started) is a self-serve UI that calls the back end on your behalf, not a separate back-end option.

<Note>
  This page describes the standard integration: **Flinks Connect** on the front end plus **API requests** on the back end. If you want data pushed to you automatically instead of polling, see [Choosing your back end](#choosing-your-back-end) below.
</Note>

## Prerequisites

Before you begin, make sure you have the following credentials and values. You can find these in your [Flinks Dashboard](./getting-started) or from your Flinks representative.

| Value                          | Purpose                                                                                                                                            |
| :----------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Customer ID** (`customerId`) | Identifies your account. Used in every API URL path.                                                                                               |
| **Instance name**              | Your regionally-scoped instance (for example, sandbox vs. production). Determines your base URLs. See [Instances](../getting-started/instances).   |
| **Secret key**                 | The unique key Flinks provides during integration. Passed in the `flinks-auth-key` header of `/GenerateAuthorizeToken` to create authorize tokens. |
| **Authorize token**            | A single-use token generated from your secret key. Passed to Flinks Connect (URL parameter) or to `/Authorize` (`flinks-auth-key` header).         |
| **iframe base URL**            | The Flinks Connect endpoint you launch, in the form `https://yourinstance-iframe.private.fin.ag/`.                                                 |

<Warning>
  The **secret key** and the **authorize token** are not the same. Use the secret key only to generate authorize tokens; use the authorize token to authenticate Flinks Connect or `/Authorize`. See [Set Up Authorization](./setup-authorization).
</Warning>

## End-to-end flow

The diagram below shows the standard integration happy path.

```mermaid theme={null}
sequenceDiagram
    participant App as Your App / Back end
    participant User as End User
    participant Connect as Connect Widget
    participant API as Connect API

    App->>API: /GenerateAuthorizeToken (token #1)
    API-->>App: authorize token
    App->>Connect: Launch iframe with authorize token
    User->>Connect: Select FI, enter credentials, complete MFA
    Connect-->>App: loginId (and optional accountId)
    App->>API: /GenerateAuthorizeToken (fresh token #2)
    API-->>App: authorize token
    App->>API: /Authorize (loginId, MostRecentCached: true)
    API-->>App: 200 + requestId
    App->>API: /GetAccountsDetail (requestId)
    alt 202: operation pending
        API-->>App: 202 (processing)
        loop Poll every ~10 seconds
            App->>API: /GetAccountsDetailAsync (requestId)
            API-->>App: 202 (still processing)
        end
        API-->>App: 200 (account data)
    else 200: data ready
        API-->>App: account data
    end
```

## Step-by-step

<Steps>
  <Step title="Generate an authorize token to launch the iframe">
    Call [`/GenerateAuthorizeToken`](../../api/authorize/endpoints/generate-authorize-token) with your **secret key** in the `flinks-auth-key` header.

    * **Input:** secret key (header)
    * **Output:** an authorize token that is single-use and active for 15 minutes.

    Pass this token to Flinks Connect using the `authorizeToken` URL parameter:

    ```url URL theme={null}
    https://yourinstance-iframe.private.fin.ag/?redirectUrl=flinks.com&authorizeToken=d65f1adb-8ebc-48dc-be8b-20c773ba1565
    ```
  </Step>

  <Step title="The end user completes Flinks Connect">
    The end user selects their financial institution, enters their credentials, and completes multi-factor authentication (MFA) if their bank requires it. Flinks Connect handles all bank processes, edge cases, and errors on your behalf.

    When the connection succeeds, capture the `loginId` (and optionally an `accountId`) from the Flinks Connect [event listener](./flinks-connect/use-event-listener) or the [redirect URL](./next-steps#save-your-loginids).

    * **Output:** `loginId`, a permanent token representing the saved connection. Store it securely on your servers; never expose it publicly.

    <Note>
      The `loginId` does not expire and is required for all future data retrieval. See [Key Concepts](../getting-started/key-concepts#loginid).
    </Note>
  </Step>

  <Step title="Generate a fresh authorize token">
    The token you generated in step 1 was consumed when you launched Flinks Connect. Authorize tokens are **single-use**, so call [`/GenerateAuthorizeToken`](../../api/authorize/endpoints/generate-authorize-token) again to create a **new** token before calling `/Authorize`.

    * **Input:** secret key (header)
    * **Output:** a fresh authorize token.

    <Tip>
      Generate a fresh authorize token continuously across the session, any time you are about to make a call that requires one. Reusing a consumed token will fail authentication.
    </Tip>
  </Step>

  <Step title="Call /Authorize in cached mode">
    Call [`/Authorize`](../../api/authorize/endpoints/authorize) with the `loginId`, passing the fresh authorize token in the `flinks-auth-key` header. Use cached mode (`MostRecentCached: true`) to open a session against the data that was just collected.

    ```bash Authorize theme={null}
    curl --request POST \
      --url https://yourinstance-api.private.fin.ag/v3/{customerId}/BankingServices/Authorize \
      --header 'Content-Type: application/json' \
      --header 'flinks-auth-key: {authorize_token}' \
      --data '{
        "LoginId": "your-login-id",
        "MostRecentCached": true
      }'
    ```

    In cached mode the response is `200`, because the end user already completed any required authentication in the iframe.

    * **`200`:** Authenticated. Use the returned `RequestId` to retrieve data (next step).
    * **Output:** a `RequestId`, a session token used to call the data endpoints. It cannot be reused.
  </Step>

  <Step title="Retrieve account data">
    Send a `POST` request to [`/GetAccountsDetail`](../../api/connect/endpoints/account-linking/get-accounts-detail) with the `RequestId` in the body. (Use [`/GetAccountsSummary`](../../api/connect/endpoints/account-linking/get-accounts-detail) if you only need summary-level data.)

    Handle the response by status:

    * **`200`:** Data is ready. The response contains the full account payload.
    * **`202`:** The operation is still processing. Poll for the result (next step). A `202` is expected on the initial call.
  </Step>

  <Step title="Poll on 202 until data is ready">
    When `/GetAccountsDetail` returns `202`:

    1. Call [`/GetAccountsDetailAsync`](../../api/connect/endpoints/account-linking/get-accounts-detail-async) with the same `RequestId` as a path parameter (this is a `GET` request).
    2. If the response is `202`, the data is still processing. **Wait \~10 seconds**, then poll again.
    3. Repeat until you receive a `200`, which contains the same payload as a `200` from `/GetAccountsDetail`.
    4. Set a maximum timeout of 30 minutes to avoid an infinite polling loop.

    <Note>
      `/GetAccountsDetailAsync` is not a separate data endpoint. It is the polling mechanism for `/GetAccountsDetail`. See [Retrieve Account Data](./retrieve-account-data#poll-getaccountsdetailasync-on-202).
    </Note>
  </Step>

  <Step title="(Optional) Enrich the data with Attributes">
    If your use case needs enriched insights, call the Attributes / Enrich endpoint on demand with the `RequestId`.

    <Note>
      Attributes are fetched **on demand** by making an API request. They are not returned automatically with account data and are not delivered by webhook.
    </Note>
  </Step>
</Steps>

## Choosing your back end

This page uses **API requests with polling** on the back end. If you would rather have data pushed to you automatically when processing completes, without writing polling logic, set up [Webhooks](../webhooks/introduction) instead.

For a side-by-side comparison of API requests vs. Webhooks, see [Choose a Back-End Solution](./choose-a-backend-solution).

## Next steps

<CardGroup cols={2}>
  <Card title="Set Up Authorization" icon="key" href="./setup-authorization">
    Generate and pass authorize tokens correctly.
  </Card>

  <Card title="Retrieve Account Data" icon="download" href="./retrieve-account-data">
    Full detail on the data retrieval and polling flow.
  </Card>

  <Card title="Handled Errors" icon="triangle-exclamation" href="./flinks-connect/handled-errors">
    Understand how Flinks reports and handles errors.
  </Card>

  <Card title="Resume and Reconnect" icon="rotate" href="./resume-and-reconnect">
    Re-establish a connection for a returning user.
  </Card>

  <Card title="Webhooks" icon="webhook" href="../webhooks/introduction">
    Receive data automatically instead of polling.
  </Card>
</CardGroup>