> ## 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 banks with Plaid
> Set up your Plaid developer account, enter credentials in the Breadbox setup wizard, and link your first bank account using the Plaid Link flow.
If your bank is covered by [Teller](/connections/teller), it's often the simpler way to start — real-data testing doesn't require Plaid's production approval process or a paid tier. Plaid offers the widest US coverage once you're ready for production.
Plaid connects Breadbox to thousands of US financial institutions, retrieves up to two years of transaction history on first connection, and keeps your data current through a combination of scheduled syncing and real-time webhooks. This page walks you through everything you need as a user to get a Plaid connection running.
## What you need
You need a Plaid developer account before you can configure Breadbox. A free account gives you access to the sandbox and development environments — no payment information required.
[Create a Plaid account at plaid.com](https://plaid.com) to get your Client ID and Secret.
## Plaid environments
Plaid has three environments. You choose one during the Breadbox setup wizard, and it determines which banks you can connect and whether there are costs.
| Environment | What it connects to | Cost |
| ----------- | ------------------------------------------------------------------------------- | ------------------------------------- |
| Sandbox | Simulated bank data only. Use this to try Breadbox without linking a real bank. | Free |
| Development | Real bank accounts. Limited to 100 live connections total. | Free |
| Production | Real bank accounts. Unlimited connections. | \~\$1.50 per connected bank per month |
Start with Development to test with your real bank accounts at no cost. Switch to Production only when you need more than 100 connections or are ready for a permanent setup.
## Enter your Plaid credentials
During the Breadbox first-run setup wizard, Step 2 asks for your Plaid credentials.
Log in at [dashboard.plaid.com](https://dashboard.plaid.com) and navigate to **Keys**. Copy your **Client ID** and the **Secret** for the environment you want to use (sandbox, development, or production).
In the Breadbox setup wizard (Step 2), paste your Client ID and Secret into the corresponding fields, then select the environment from the dropdown.
Click **Validate and Continue**. Breadbox makes a live test call to Plaid to confirm your credentials are correct before saving them. If the call fails, check that you copied the secret for the right environment.
Your credentials are stored encrypted in your Breadbox database and never exposed through the API. If you prefer to supply them as environment variables (`PLAID_CLIENT_ID`, `PLAID_SECRET`, `PLAID_ENV`), those take precedence over the database values and the fields become read-only in Settings.
## Connect a bank account
Once your Plaid credentials are saved, you can add bank connections from the **Connections** page.
Go to **Connections** → **Connect New Bank**. Select the family member this bank account belongs to, then click **Continue to Bank Selection**.
Breadbox opens the Plaid Link dialog in your browser. Search for your bank, enter your online banking username and password, and complete any multi-factor authentication your bank requires. Plaid handles the login flow directly — Breadbox never sees your bank credentials.
After you authenticate, Plaid shows the accounts available at your institution. Select the accounts you want Breadbox to track, then click **Continue**.
Breadbox immediately begins pulling your transaction history. Plaid requests up to two years of transactions on the first connection. The sync runs in the background — you can navigate away and check back on the Connections page. The status shows **Active** once the initial sync completes.
## Transaction history
On the first connection, Breadbox requests up to 730 days (approximately two years) of transaction history from Plaid. This is the maximum Plaid allows. For older transactions, use the [CSV import](/connections/csv-import) to supplement the Plaid connection.
Subsequent syncs are incremental — only new, changed, or removed transactions are fetched, which keeps sync fast.
## Webhook setup for near-real-time updates
Without a webhook, Breadbox syncs your Plaid connections on a fixed schedule (every 4–24 hours depending on your configuration). With a webhook, Plaid notifies Breadbox within minutes of new transactions being available, and Breadbox syncs immediately.
To enable webhooks:
Your Breadbox instance needs a public HTTPS URL. If you run Breadbox at home, [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) is a free option that creates a stable public URL without port forwarding.
In **Settings** (or during setup wizard Step 4), enter your public base URL. Breadbox will register `{your-url}/webhooks/plaid` as the webhook endpoint with Plaid automatically when you create new connections.
You can skip this step and add a webhook URL later in **Settings** without re-linking any banks.
## Re-authentication
Plaid connections occasionally require re-authentication. This happens when:
* Your bank password changes.
* Your bank's multi-factor authentication session expires.
* OAuth consent is revoked or about to expire.
When Breadbox detects this, the connection status changes to **Re-auth Needed** (yellow) or **Error** (red) in the Connections list. Syncing stops until you re-authenticate.
To re-authenticate:
Go to **Connections** and click **Re-authenticate** on the affected connection, or click **View** then **Re-authenticate** from the connection detail page.
Breadbox opens the Plaid Link dialog in update mode. Log in to your bank again. You do not need to re-select your accounts.
After you complete the login, Breadbox immediately triggers a sync. The connection status returns to **Active**.
## Disconnecting a bank
To remove a Plaid connection, click **Remove Connection** on the connection detail page and confirm the dialog. The same operations — list, status, manual sync — are also exposed via the [Connections API](/api/overview).
Removing a connection:
* Immediately revokes Breadbox's access at Plaid. This also stops any Plaid billing for that connection.
* Sets the connection status to **Disconnected** in Breadbox.
* **Preserves all transaction history.** Previously synced transactions remain in your database.
Removing a connection stops billing for that Plaid item immediately. If you want to resume syncing in the future, you must re-link the bank from scratch, which starts a new billing cycle.
## Production costs
Plaid's Production environment is billed at approximately \$1.50 per connected bank (called an "item") per month. Each bank you connect — regardless of how many accounts it has — counts as one item. The Development environment is free up to 100 items.
Syncing more frequently does not increase your cost. Production billing is per item per month, not per API call.