Apps on BankSync

A BankSync app is your product, installed into someone else's BankSync workspace. They own the workspace. You hold a grant against the banks they chose to give you, you read only those, and — if you ask for it — the data arrives on your own endpoint as it syncs.

The unit you build against is the install: one app, in one workspace, holding one grant. Not a user, not a bank connection. Everything else in this section is a detail of getting an install created, keeping it working, and reading through it.

Is an app what you want?#

There are four ways data leaves BankSync, and picking the wrong one costs real time. The question that separates them is whose workspace holds the data, and who is paying.

An API key is a secret that gives programmatic access to your workspace over the REST API and the MCP server. It is the right tool when the data you want is already yours. It is the wrong tool for a product with users, because you would be handing every user the same credential to your own workspace.

A destination — Google Sheets, Notion, a database, a webhook — pushes a workspace's synced data out to a tool. Also yours, also not a product.

A client portal is a child workspace under your parent workspace, for an accountant or bookkeeper managing clients. Every portal bills to the parent's subscription, and the parent's owner and admins hold implicit authority over every portal beneath it. That is exactly right for an accountant and exactly wrong for a software product: your users would be paying through you, and you would hold administrative access to all of their bank data. If you are building something your users install, you want an app.

The shape of it#

Five steps, each with its own page.

1. Register the app. Its name, slug, branding, and the scopes it may request, plus one or more client credentials. See Register an OAuth app.
2. Declare a manifest. What your app reads, what furniture it creates in the workspace (tables, feeds, enrichment steps), and where events should be delivered. See Building a BankSync app.
3. Send users to the connect link. https://app.banksync.io/connect/<slug> — BankSync shows them who is asking and for what, signs them in or signs them up, walks them through connecting their bank, takes their approval, and hands them back to you with an authorization code. See The connect link.
4. Read, and receive. Exchange the code for a token and read /v1 on that user's behalf; take signed events on your endpoint as their data syncs.
5. List it, if you want to be found. See Listing and publishing your app.

Your users never see a BankSync workspace, dashboard or navigation at any point in that flow. The connect page renders before anyone signs in, on purpose: the person following it has usually never heard of BankSync, and they should learn who your app is and what it will read before they are asked to make an account.

Returning users#

A user who already installed you and needs to add a second bank does not go back through the full flow. The connect link takes an intent:

https://app.banksync.io/connect/<slug>?intent=add_bank&return_to=https%3A%2F%2Fyourapp.example%2Fdone

intent=add_bank skips the gate and the consent screen — they already installed you and already saw what you can read — runs the bank step, and returns them to your own page. intent=reauth does the same for one connection that has broken. Neither mints a new authorization code, because you already hold a grant.

Note there is no workspace id anywhere in that URL. A third party cannot know which workspace a browser is signed in to, and with the connect link it does not need to.

Next#

• Register an OAuth app — the app record, its client credentials, and the redirect URIs every return URL must match.
• Building a BankSync app — the manifest contract, the install lifecycle, your endpoint and its signed events.
• The connect link — every query parameter, the three intents, the return_to rules, and the round trip back.
• Listing and publishing your app — review, and being found.