Skip to main content
A connection in Breadbox is a link between your self-hosted instance and a bank account source. Each connection belongs to a family member and is managed through the admin dashboard. Once a connection is established, Breadbox pulls in your transactions automatically — or lets you import them manually — and keeps everything in your local database.

​
Provider types

Breadbox supports three ways to bring in bank data. Each has different setup requirements and capabilities.

Plaid

Connects to thousands of US financial institutions using Plaid’s secure link flow. Supports automatic sync and real-time webhooks.

Teller

An alternative to Plaid for some US banks. Uses mTLS-based authentication and the same dashboard-driven connection flow.

CSV import

Manually import transactions from a CSV file your bank provides. Works for any institution, with no API credentials required.

​
When to use each provider

ProviderBest for
PlaidMost US banks and credit cards. Widest coverage, automatic sync, balance tracking.
TellerBanks or credit unions where Teller has coverage but Plaid does not, or as an alternative to Plaid.
CSVInstitutions not covered by Plaid or Teller, historical data imports, and one-time migrations from other tools.

​
Connection statuses

Every connection has a status that tells you whether Breadbox can sync data from it.
StatusMeaning
activeThe connection is healthy. Sync runs on schedule.
pending_reauthYour session or OAuth consent with the bank is about to expire. Re-authentication is needed soon but sync is still working.
errorSync is blocked. The bank rejected the stored credentials or a login change occurred. You must re-authenticate before data will update.
disconnectedYou 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.
Disconnecting a bank does not delete your transaction history. All previously synced transactions remain in your database and can still be queried.

​
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.
Your webhook endpoint must be reachable from the internet. If you run Breadbox at home or behind a firewall, Cloudflare Tunnel is a free option that creates a stable public URL for your local instance.
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.
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.

​
Next steps

Connect with Plaid

Set up Plaid credentials and link your first bank account.

Connect with Teller

Configure Teller and enroll a bank using the Teller Connect flow.

Import from CSV

Upload a CSV export from your bank and map columns to Breadbox fields.