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

# Relinking 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.

```http theme={null}
Authorization: Bearer <fluz-user-access-token>
```

## Detecting that a relink is needed

There are two reliable signals:

1. `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.)
2. `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`

```graphql theme={null}
mutation CreatePlaidLinkToken($input: CreatePlaidLinkTokenInput!) {
  createPlaidLinkToken(input: $input) {
    linkToken
    expiration
    requestId
    mode
  }
}
```

```json theme={null}
{
  "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`.

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

```json theme={null}
{
  "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.

<br />