Relinking Disconnected Bank Accounts

A previously linked Plaid connection can drop — for example, when the user changes their bank credentials. While it's disconnected, Fluz can't fetch updated balances, so it must be repaired with a Plaid update-mode Link flow before balances and spend power will refresh again.

Auth

Call /api/v1/graphql with a Fluz user Bearer access token that includes MANAGE_PAYMENT. Basic auth is not allowed on these fields.

Authorization: Bearer <fluz-user-access-token>

Detecting that a relink is needed

There are two reliable signals:

refreshPlaidBankConnections returns verifyMembers. Each entry identifies a connection that needs repair; use its platformItemId to start the relink flow below. (See Managing Bank Account Spend Power for that mutation.)
createPlaidLinkToken fails with No active Plaid connection found for the provided platformItemId. — the stored connection is no longer relinkable; guide the user through a new bank link instead (see Linking a Plaid Bank Account).

Relink flow

You'll need the stored platformItemId for the disconnected connection.

1. Create a Link token with the stored `platformItemId`

mutation CreatePlaidLinkToken($input: CreatePlaidLinkTokenInput!) {
  createPlaidLinkToken(input: $input) {
    linkToken
    expiration
    requestId
    mode
  }
}

{
  "input": {
    "platformItemId": "plaid-item-id"
  }
}

TGS uses platformItemId to retrieve the Plaid access token from identity-service, then asks identity-service to create a Plaid update-mode Link token. The access token is never returned to the caller.

For native relink, also pass deviceOs as IOS or ANDROID.

2. Open Plaid Link

Initialize Plaid Link with the returned linkToken.

3. Complete the relink

In Plaid Link's onSuccess, complete the flow with both publicToken and the same platformItemId.

mutation CompletePlaidLink($input: CompletePlaidLinkInput!) {
  completePlaidLink(input: $input) {
    requiresAddress
    bankAccountId
    bankInstitutionAuthId
    newlyLinkedBankInstitutionAuthId
    bankInstitutionName
    platformItemId
    bankAccounts {
      bankInstitutionAuthId
      bankAccountId
      bankName
      lastFour
      type
      subtype
    }
  }
}

{
  "input": {
    "publicToken": "public-sandbox-...",
    "platformItemId": "plaid-item-id"
  }
}

4. Update the stored `platformItemId`

Update your stored platformItemId from the response if it changed. If it isn't returned, call getPlaidBankAccounts for the user and store the persisted platformItemId from that response.

Using the Web SDK for relink

The shared startPlaidLink helper in Linking a Plaid Bank Account handles both cases. Call startPlaidLink(existingPlatformItemId) to repair a disconnected connection; call startPlaidLink() with no argument for a brand-new link.

Error handling

If createPlaidLinkToken fails with No active Plaid connection found for the provided platformItemId., treat the stored connection as no longer relinkable and guide the user through a new bank link.

If a user starts a new link for the same institution instead of choosing relink, complete it as a normal new link — identity-service owns bank-account dedupe and repair. Store the returned platformItemId after completion.

Linking a Plaid Bank Account — connect a new account.
Managing Bank Account Spend Power — read balances and spend power, and detect disconnects via verifyMembers.
Getting Bank Account Transaction Data — read historical bank transactions.