> ## Documentation Index
> Fetch the complete documentation index at: https://breadbox-mintlify-7401d007.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your bank accounts

> Learn how Breadbox connects to your banks via Plaid, Teller, or CSV import, and how to manage connection health from the admin dashboard.

A **connection** in Breadbox is the link between your self-hosted instance and a bank data source, owned by a specific family member. Once a connection is established, Breadbox pulls in that person's transactions automatically — or lets you import them manually — and keeps everything in your local database.

## Providers supported

Breadbox currently supports three ways to bring in bank data. If you're setting up for the first time, **Teller is the easiest starting point**: the free Development tier connects to real accounts immediately, with no production approval process to wait on.

<Columns cols={3}>
  <Card title="Teller" icon="landmark" href="/connections/teller">
    Recommended starter. Real bank connections on the free Development tier without a production approval process. Uses mTLS-based authentication.
  </Card>

  <Card title="Plaid" icon="building" href="/connections/plaid">
    Widest US coverage — thousands of institutions, automatic sync, webhooks, and balance tracking. Worth the extra setup once you're ready for production.
  </Card>

  <Card title="CSV import" icon="file-spreadsheet" href="/connections/csv-import">
    Works for any institution, with no API credentials. Useful for banks Plaid and Teller don't cover, historical data, and migrations from other tools. <Badge color="blue" icon="hammer">BETA</Badge>
  </Card>
</Columns>

More provider integrations are on the roadmap — see the [GitHub repo](https://github.com/canalesb93/breadbox) for current status.

## Connection statuses

Every connection has a status that tells you whether Breadbox can sync data from it.

| Status           | Meaning                                                                                                                                 |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `active`         | The connection is healthy. Sync runs on schedule.                                                                                       |
| `pending_reauth` | Your session or OAuth consent with the bank is about to expire. Re-authentication is needed soon but sync is still working.             |
| `error`          | Sync is blocked. The bank rejected the stored credentials or a login change occurred. You must re-authenticate before data will update. |
| `disconnected`   | You intentionally removed this connection. Your historical transaction data is preserved, but no new data will be fetched.              |

The admin dashboard shows a color-coded badge for each status: green for active, yellow for pending re-authentication, red for error, and gray for disconnected.

<Note>
  Disconnecting a bank does not delete your transaction history. All previously synced transactions remain in your database and can still be queried.
</Note>

## How automatic sync works

Breadbox keeps your data up to date using two complementary mechanisms:

**Scheduled sync (cron):** Breadbox syncs all active connections on a regular interval you configure during setup (every 4, 8, 12, or 24 hours). This ensures data stays fresh even if event-driven updates are unavailable.

**Webhook-driven sync:** When you configure a public webhook URL, Plaid and Teller send a notification to Breadbox as soon as new transactions are available. Breadbox immediately triggers an incremental sync for that connection. This gives you near-real-time updates without relying solely on the polling interval.

If no webhook URL is configured, Breadbox falls back to cron-only syncing.

<Note>
  Your webhook endpoint must be reachable from the internet. If you run Breadbox at home or behind a firewall, [Remote Hosting](/installation/remote-hosting) covers four options — exe.dev, Cloudflare Tunnel, Caddy on a VPS, and Tailscale Funnel — that each give you a stable public URL.
</Note>

CSV connections do not support automatic sync. You import new data manually whenever you want to add transactions.

## Managing connections from the admin dashboard

The **Connections** page in the admin dashboard lists every bank connection with its current status, family member, account count, and last sync time.

From this page you can:

* **View** a connection's accounts, balances, and sync history.
* **Sync now** to trigger an immediate incremental sync for any active connection.
* **Re-authenticate** connections that are in `error` or `pending_reauth` status. Breadbox opens the bank's secure login flow in the same browser session. Your stored transaction history is not affected.
* **Remove** a connection to stop future syncing. Transaction data is kept.

The same operations are available programmatically via the [Connections API](/api/overview).

<Warning>
  Removing a Plaid or Teller connection immediately revokes Breadbox's access at the provider level and stops any billing for that connection. This action cannot be undone — you would need to re-link the bank to resume syncing.
</Warning>

## Next steps

<Columns cols={3}>
  <Card title="Connect with Teller" icon="plug" href="/connections/teller">
    Configure Teller and enroll a bank using the Teller Connect flow.
  </Card>

  <Card title="Connect with Plaid" icon="plug" href="/connections/plaid">
    Set up Plaid credentials and link your first bank account.
  </Card>

  <Card title="Import from CSV" icon="upload" href="/connections/csv-import">
    Upload a CSV export from your bank and map columns to Breadbox fields.
  </Card>
</Columns>