Customer keys
Create, back up, load and rotate the customer key that unlocks saved bank logins in v2.
A customer key is a seed (blseed_v1_…) that stays in your systems. It unlocks your saved bank logins and decrypts results. Banklink holds only its public half.
You need one for saved connections. One-off fetches with profiles.syncOnce use a throwaway key and don’t need one.
Create one
Section titled “Create one”Register a customer key once per organisation. Either let the SDK generate the seed:
const banklink = new BanklinkV2({ apiKey: process.env.BANKLINK_API_KEY! });const seed = await banklink.keys.init();await saveToYourSecretManager(seed); // do this before anything elseOr generate and back up the seed yourself first, then register it with banklink.keys.init(seed). That’s the safer order: the seed is in your secret manager before Banklink knows about it.
Back it up
Section titled “Back it up”- Banklink can’t recover it. Only the public half is registered. There is no reset.
- If you lose it, relink every account that used it. The saved logins can’t be unlocked without it.
- Store it in a secret manager, not in source code, environment files checked into git, or logs.
Load it
Section titled “Load it”Give the SDK the seed when you construct the client, either directly with key or from a function with keyProvider:
import { BanklinkV2 } from '@banklink/sdk/v2';import { FileVersionCache } from '@banklink/sdk/local';
const banklink = new BanklinkV2({ apiKey: process.env.BANKLINK_API_KEY!, keyProvider: async () => loadSeedFromYourSecretManager(), hostVersionCache: new FileVersionCache('/private/app-owned-directory/host-version'),});Pass one of key or keyProvider, not both. keys.current() returns the registered public key and throws KeyMismatchError if your seed doesn’t match it.
hostVersionCache remembers the newest worker list the SDK has verified, so an older list can’t be replayed to it after a restart. FileVersionCache keeps it in a private file owned by one process. To share it across processes, implement read() and write() on your own store.
Rotate it
Section titled “Rotate it”const newSeed = await generateAndBackUpNewSeed();await banklink.keys.rotate(newSeed);Rotation re-wraps each saved login to the new key on your side. It doesn’t sign in to any bank. If it’s interrupted, run it again with the same new seed. Keep the old seed until it completes. keys.pending() shows a rotation that hasn’t finished.
If the old seed may have leaked, pass { rollDataKeys: true }. That also runs a verify job for each saved connection straight away, which signs in to each bank. Banks that ask for a one-time PIN need onOtp.