Link

Link is the user-facing connection flow: institution search, authentication (OAuth simulation, credentials, wallet address, or file upload), optional MFA, account selection, and consent. It renders as an iframe modal your page opens with a link_token.

Install

npm install @feelconnect/link

Opening Link

Create a link_token server-side (reference), then open the modal. The vanilla API returns a handle; the React hook manages the handle's lifecycle for you.

import { useFeelConnectLink } from "@feelconnect/link";

const { open, ready, exit } = useFeelConnectLink({
  linkToken,
  onSuccess: (publicToken, metadata) => exchangeOnServer(publicToken),
  onExit: (error) => error && report(error),
  onEvent: (name, data) => analytics.track("link_" + name, data),
});

// <button onClick={open} disabled={!ready}>Connect</button>

Options

Success metadata

{
  "institution": {
    "id": "inst_meridian_trust",
    "name": "Meridian Trust"
  },
  "accounts": [
    {
      "id": "acct_9hK2mQxP7cW1nR4tYb8s",
      "name": "Everyday Checking",
      "mask": "4821",
      "type": "depository"
    },
    {
      "id": "acct_5tGb2VnM8kQ4wZ1xLp0d",
      "name": "Cashback Card",
      "mask": "0093",
      "type": "credit"
    }
  ]
}

{
  "code": "INSTITUTION_DOWN",
  "message": "This institution is temporarily unavailable."
}

Flow lifecycle

A completed session walks these steps; onEvent fires at each transition:

• Institution search — typed groups: banks, payment apps, investments, crypto, business.
• Authentication — OAuth consent simulation, credential form, wallet address entry, or CSV/OFX upload, depending on the institution.
• MFA challenge — only when the institution (or user_mfa in sandbox) requires it.
• Account selection — the user picks which accounts to share.
• Consent — the product scopes from your link_token are shown and granted.
• Handoff — Link emits success and closes itself.

postMessage protocol

The SDK and iframe communicate with origin-checked postMessage events. You normally never touch these — the SDK maps them onto callbacks — but they matter if you build your own wrapper:

Update mode

When an institution invalidates credentials, the item's status becomes login_required and you receive an item.error webhook. Reconnect the same item — keeping its item_id, accounts, and cursors — by creating a link token with update_item_id:

curl https://api.feelconnect.dev/v1/link/token/create \
  -H "Authorization: Bearer $FEELCONNECT_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user":{"client_user_id":"user-123"},"products":["transactions"],"update_item_id":"item_7dJ3nWqZ5xC9vK1mTf4g"}'

• Link skips institution search and jumps straight to re-authentication for that institution.
• On success the existing item returns to active and a transactions.sync_updates_available webhook follows. Your stored access_token keeps working — update mode needs no exchange, so you can ignore the public_token from onSuccess.
• If you do exchange it, the item's access_token is rotated: the response carries rotated: true and the previous token stops working immediately, so replace every stored copy.
• update_item_id must belong to the same client_user_id, otherwise user_mismatch is returned.
• In sandbox, force this state with /v1/sandbox/item/reset_login.