Skip to content

Banklink v2Customer-held keys and one-off fetches, through the Node.js SDK. v1 is unchanged.Migration guide

Banklink Docs

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.

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 else

Or 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.

  • 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.

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.

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.