From c51cfa25e0940eb95ae60747035c58efad3b9633 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Thu, 25 Jun 2026 02:04:42 +0000 Subject: [PATCH] docs: document SimpleFIN sync discovery and per-account owner override --- connections/overview.mdx | 14 ++++-- connections/simplefin.mdx | 94 +++++++++++++++++++++++++++++++++++ docs.json | 1 + guides/on-demand-analysis.mdx | 12 +++-- 4 files changed, 115 insertions(+), 6 deletions(-) create mode 100644 connections/simplefin.mdx diff --git a/connections/overview.mdx b/connections/overview.mdx index 3751f59..5badcb4 100644 --- a/connections/overview.mdx +++ b/connections/overview.mdx @@ -7,9 +7,9 @@ A **connection** in Breadbox is the link between your self-hosted instance and a ## 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. +Breadbox currently supports four 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. - + Recommended starter. Real bank connections on the free Development tier without a production approval process. Uses mTLS-based authentication. @@ -18,6 +18,10 @@ Breadbox currently supports three ways to bring in bank data. If you're setting Widest US coverage — thousands of institutions, automatic sync, webhooks, and balance tracking. Worth the extra setup once you're ready for production. + + Token-paste aggregator via the SimpleFIN Bridge. One token spans every bank linked at the bridge, and new banks added there appear automatically on the next sync. + + Works for any institution, with no API credentials. Useful for banks Plaid and Teller don't cover, historical data, and migrations from other tools. BETA @@ -77,7 +81,7 @@ The same operations are available programmatically via the [Connections API](/ap ## Next steps - + Configure Teller and enroll a bank using the Teller Connect flow. @@ -86,6 +90,10 @@ The same operations are available programmatically via the [Connections API](/ap Set up Plaid credentials and link your first bank account. + + Paste a SimpleFIN setup token to pull in every bank linked at your bridge. + + Upload a CSV export from your bank and map columns to Breadbox fields. diff --git a/connections/simplefin.mdx b/connections/simplefin.mdx new file mode 100644 index 0000000..b360ff4 --- /dev/null +++ b/connections/simplefin.mdx @@ -0,0 +1,94 @@ +--- +title: "Connect banks with SimpleFIN" +description: "Paste a SimpleFIN setup token to bring banks into Breadbox through the SimpleFIN Bridge — including banks you add at the bridge after connecting." +sidebarTitle: "SimpleFIN" +--- + +[SimpleFIN](https://www.simplefin.org/protocol.html) is a token-paste, poll-only bank-data protocol commonly used by the self-hosting community via the hosted [SimpleFIN Bridge](https://bridge.simplefin.org) or a self-run server. It is the simplest provider Breadbox supports: no OAuth dialog, no SDK, no webhooks — just paste a setup token and Breadbox starts polling. + +Use SimpleFIN when you already use the SimpleFIN Bridge, when your bank isn't covered by [Plaid](/connections/plaid) or [Teller](/connections/teller), or when you want a single token that spans multiple banks. + +## What you need + +- A **SimpleFIN account** at [bridge.simplefin.org](https://bridge.simplefin.org) (or a self-run server) with at least one bank linked at the bridge. +- A **setup token** generated from your bridge's setup page. Setup tokens are one-time-use and short-lived — generate one immediately before pasting it into Breadbox. +- The `simplefin_enabled` opt-in toggle set to `true` in Breadbox (either via the `SIMPLEFIN_ENABLED` environment variable or **Settings → Providers**). There is no per-server credential to configure. + +## Connect a bank + + + + Sign in at [bridge.simplefin.org](https://bridge.simplefin.org), link your banks if you haven't already, and click **Create Token**. Copy the base64 setup token — it is single-use. + + + Go to **Connections** → **Connect New Bank**, select the household member who will own this connection, and choose **SimpleFIN** as the provider. + + + Paste the token into the prompt and submit. Breadbox claims the token (exchanging it for an access URL), stores the credential encrypted, and discovers the accounts available at the bridge. + + + Breadbox polls the bridge for about one year of transaction history on the first sync. Status flips to **Active** once the initial sync completes. + + + +One SimpleFIN connection covers **every bank you have linked at the bridge** — you don't run the connect flow once per bank. + +## Automatic account discovery on every sync + +SimpleFIN is an aggregator: the same access URL covers every bank you've linked at the bridge, and you can keep adding banks there at any time. To handle this, **every sync re-reads the full account list** from the bridge and Breadbox upserts any new accounts before processing transactions. + +That means: + +- A bank you link at the bridge **after** connecting Breadbox shows up automatically on the next scheduled sync — there is no "rescan accounts" button to hit and no need to re-paste your token. +- Existing accounts keep their settings (display name, exclusion flag, owner override). Only metadata is upserted on discovery — balances refresh on their normal path. +- If you want a newly added bank to appear sooner than the next scheduled run, click **Sync now** on the connection. + +Plaid and Teller pin the account set at connect time, so this behavior is specific to SimpleFIN. + +## Mixed-owner bridges and per-account owner override + +A single SimpleFIN token often spans accounts belonging to **different household members** — for example, one partner links both their and their partner's banks at the same bridge. The Breadbox connection has a single owner, but you can reassign **individual accounts** to another household member using the per-account owner override. + +### Set the owner from the admin dashboard + +1. Open the account from **Accounts** (or from its connection). +2. In the **Settings** section of the account-detail page, change the **Owner** select to the household member who should own this account. +3. Save. The change takes effect immediately for new and existing transactions on that account — no resync, no backfill. + +Selecting **Inherit from connection** clears the override and the account falls back to the connection's owner. + +### Set the owner from the API + +The override is exposed on `PATCH /api/v1/accounts/{id}` as the optional `owner_user_id` field. Pass a member's `short_id` to set it, or an empty string to clear it. + +```json +{ + "owner_user_id": "u8Xk2p9q" +} +``` + +### Attribution precedence + +The effective owner of each transaction resolves at read time in this order: + +1. **Per-transaction attribution** (from [account links](/transactions/overview), e.g. a child's purchases routed away from the parent who owns the card). +2. **Per-account owner override** (`accounts.owner_user_id`, the field you set above). +3. **Connection owner** (`bank_connections.user_id`, set when the connection was created). + +The first one that's set wins. Because attribution resolves on the read path, reassigning an account's owner re-routes **every existing transaction** on that account across per-user totals, summaries, and category aggregations without any backfill job. + +## Re-authentication + +SimpleFIN tokens don't expire on a schedule, but the bridge can revoke the underlying access URL (for example, if you regenerate it from the bridge UI). When a sync starts returning `403`, the connection moves to **Re-auth Needed**. + +To re-authenticate, generate a fresh setup token from the bridge, click **Re-authenticate** on the connection, and paste the new token. Breadbox rotates the stored credential in place — the connection row and all of its accounts and history are preserved. + +## Limitations + +- **No webhooks.** Sync runs on the cron schedule you configure (every 4, 8, 12, or 24 hours). There is no near-real-time path. +- **Balances and transactions only.** SimpleFIN doesn't expose investment holdings, statements, or identity data. +- **Amounts are inverted at the protocol level** — Breadbox normalizes signs internally, so amounts in the API and dashboard follow the same convention as Plaid and Teller. + +## Disconnecting + +Removing a SimpleFIN connection stops future syncs and preserves all previously synced transactions. To stop the bridge itself from holding your bank credentials, revoke the access URL from the SimpleFIN Bridge UI as well. diff --git a/docs.json b/docs.json index fd8ced7..eadf01f 100644 --- a/docs.json +++ b/docs.json @@ -72,6 +72,7 @@ "pages": [ "connections/teller", "connections/plaid", + "connections/simplefin", "connections/csv-import" ] } diff --git a/guides/on-demand-analysis.mdx b/guides/on-demand-analysis.mdx index db22f35..5a3c395 100644 --- a/guides/on-demand-analysis.mdx +++ b/guides/on-demand-analysis.mdx @@ -77,11 +77,17 @@ If the answer comes back as a single number without naming a currency, that's a ### Attribution -Breadbox supports attributing transactions to a specific household member different from the account owner — for example, a child's purchases on a shared card attributed to the child, not the parent who owns the card. Transaction queries use `COALESCE(attributed_user_id, account_owner_user_id)` to resolve the effective user, so per-user totals "do the right thing" by default. But ad-hoc questions that slice by account and then by user can double-count if you're not careful. +Breadbox supports attributing transactions to a specific household member different from the account owner — for example, a child's purchases on a shared card attributed to the child, not the parent who owns the card. The effective user resolves at read time through a three-step precedence chain: -If you ask "how much did Alice spend last month," Claude filters by `user_id` correctly. If you ask "how much spending happened on the Chase Amex last month, broken down by user," the answer will respect attribution too. But if you ask "whose transactions are on the Chase Amex," the answer might surprise you — attributed transactions show a different user than the account owner. +1. **Per-transaction attribution** (from account links, e.g. a child's purchases routed away from the parent who owns the card). +2. **Per-account owner override** (set from the account-detail Settings page, useful when a single connection — like a [SimpleFIN](/connections/simplefin) bridge — spans accounts belonging to different household members). +3. **Connection owner** (the household member who created the connection). -When in doubt, ask Claude to say whether it's using account ownership or attribution to decide who a transaction belongs to. +The first one that's set wins, so per-user totals "do the right thing" by default. But ad-hoc questions that slice by account and then by user can double-count if you're not careful. + +If you ask "how much did Alice spend last month," Claude filters by `user_id` correctly. If you ask "how much spending happened on the Chase Amex last month, broken down by user," the answer will respect attribution too. But if you ask "whose transactions are on the Chase Amex," the answer might surprise you — attributed transactions show a different user than the account owner, and the account itself may have been reassigned to another member via the per-account override. + +When in doubt, ask Claude to say which of the three levels (per-transaction, per-account override, or connection owner) it's using to decide who a transaction belongs to. ### One more, minor: pending transactions