Appearance
Authentication & API keys
The API key
Every request to the partner API carries your key in the X-Api-Key header:
sh
curl https://partner.bbapi.io/v1/partner/config \
-H "X-Api-Key: {{BB_API_KEY}}"Keys are issued in the partner portal (API keys page) and select the mode by prefix:
| Prefix | Mode |
|---|---|
bb_test_ + 32 chars | sandbox — fictional *_xf banks, free |
bb_live_ + 32 chars | live — real banks, metered |
The recognizable prefixes exist so that secret scanners (yours and GitHub's) can catch a leaked key on sight. We store only a SHA-256 fingerprint — the full key is shown exactly once, at creation.
Keys are server-side only. Never embed them in mobile apps, browser code, or URLs. The mobile Link SDKs are designed to work without any key on the device: your backend creates the connect session and hands the app a hostedUrl.
Client scoping
A client is one of your end users (POST /v1/clients). Everything a user owns — connections, accounts, transactions — is reached with the X-Client-Id header naming that client, which keeps each user's data isolated even if your backend has a bug in its own authorization. Partner-level endpoints (/v1/partner/config, /v1/providers, /v1/clients) need only the API key.
Rotation and revocation
You can hold multiple active keys per mode, so rotation has zero downtime:
- Create a new key in the portal.
- Deploy it to your servers.
- Revoke the old key — revocation takes effect immediately.
Revoke a key the moment you suspect a leak; minting a replacement first keeps your integration up while you rotate.
Rate limits
Limits are applied per key. Exceeding them returns 429 with a Retry-After header — back off for that long and retry. The official SDKs do this automatically (exponential backoff honoring Retry-After).
Request IDs
Every response — success or error — carries an X-Request-Id header (also requestId in error bodies). Log it; include it when you contact integration@budgetbakers.com and we can trace the exact request.
The other credential: webhook signing secrets
Webhook deliveries are signed with a separate secret class (whsec_…), managed on the portal's Webhooks page. Those secrets are retrievable in the portal (you need them at every verification, not just once) and rotate with an overlap window. See the webhook verification guide.