BudgetBakers Partner Docs

Appearance

Getting started ​

The BudgetBakers partner platform gives your product bank data: your users connect their bank accounts through a hosted flow, and you read accounts and transactions over a REST API — with signed webhooks telling you when things happen. This page takes you from zero to your first authenticated API call.

1. Create your partner account ​

Register in the partner portal (Google sign-in). Registration is instant and provisions sandbox access immediately — no card, no business verification. Those come later, only when you go live.

2. Get your sandbox API key ​

In the portal, open API keys and create a sandbox key. The full key — bb_test_ followed by 32 characters — is shown exactly once at creation; store it in your secret manager. Only a fingerprint is kept on our side, so a lost key means minting a new one (keys rotate with zero downtime — see Authentication).

3. Make your first call ​

Every request authenticates with the X-Api-Key header. Ask the API who you are:

sh
curl https://aisp-partner.bbapi.io/v2/partner/config \
  -H "X-Api-Key: {{BB_API_KEY}}"
json
{
  "partnerId": "2f5a1c3e-9b7d-4e21-a6c8-0d4f5e6a7b8c",
  "name": "Acme Lending",
  "mode": "sandbox",
  "capabilities": { "refresh": true, "reconnect": true, "enrichment": false }
}

capabilities is worth reading once at startup: calling a capability that is disabled for your plan returns 403 capability_disabled.

4. See the sandbox banks ​

sh
curl https://aisp-partner.bbapi.io/v2/providers \
  -H "X-Api-Key: {{BB_API_KEY}}"

In sandbox mode you get the fictional *_xf providers (e.g. Sandbox Bank XF). They behave like real banks — OAuth screens, accounts, transactions, failure scenarios — but with test data and no real credentials.

Each sandbox bank (country XF) plays one scenario:

Provider codeScenario
sandbox_pms_xfHappy path: login, accounts, balances, transactions
sandbox_multi_account_pms_xfThree accounts (EUR, USD, CZK) on one connection
sandbox_no_accounts_pms_xfLogin succeeds, the bank shares no account
sandbox_no_transactions_pms_xfAccounts without transactions
sandbox_partial_data_pms_xfTwo accounts; transactions of one fail to load
sandbox_delayed_pms_xfThe bank takes about 5 seconds per call
sandbox_auth_denied_pms_xfThe user denies access on the bank's screen
sandbox_consent_revoked_pms_xfThe bank later rejects the token refresh, as after a revoked consent
sandbox_server_error_pms_xfLogin succeeds, the account list fails with a server error

Sandbox banks are for bb_test_… keys. A bb_live_… key does not list them, the hosted bank picker of a live session does not offer them, and a connection to one (say, a sandbox provider id left in your config) is refused with 403 sandbox_provider_not_allowed.

Sandbox vs live ​

The mode is selected by the API key, nothing else:

Key prefixModeBanksBilling
bb_test_…sandboxfictional *_xf providersfree
bb_live_…livereal banksmetered

Sandbox is a complete, permanent environment — keep using it for CI and staging after you go live. Live keys become available once the go-live checks in the portal pass (card verification, automated business check, terms acceptance); your code stays identical, only the key changes.

Pick your quickstart ​

PlatformGuideWhat you build
Node.js / TypeScriptQuickstartserver integration with @budgetbakers/partner-sdk
PythonQuickstartserver integration with budgetbakers-partner-sdk
Kotlin / JavaQuickstartserver integration with com.budgetbakers:partner-sdk on the JVM

A mobile app needs no SDK of its own: it opens the hosted flow in the system browser and catches the return link, while your backend (one of the server quickstarts) holds the API key. See Mobile apps.

Next steps ​