Skip to content
Seald Healthcare SDK

Backup key and custodians

client.backupKey, the BackupKey namespace, creates and maintains the tenant’s backup key for break-glass recovery. It splits the key across custodians. No single custodian and no device alone can rebuild it. An Owner creates the key once, with three to seven custodians. The quorum is from two up to one fewer than the number of custodians. Create the key before the tenant registers its first dataset.

The calls

The samples use the allowed helper from Access decisions.

const registration = await client.backupKey.registration();
// { registrationId, state, fingerprint, custodians: [{ person, received, lastProvedAt }], quorum, mintedBy, mintedAt } | undefined


// the caller holds the Owner role
await allowed(await client.backupKey.mint({ custodians: [alice, bob, carol], quorum: 2 }));
if (registration?.state === 'pending') await client.backupKey.abandon(registration.registrationId); // before the registration completes


// a custodian, from the worklist
const delivery = await client.backupKey.receiveShare(registration.registrationId);
// { registrationId, fingerprint, code?, receipt() }
if (delivery.code) await printForPerson(delivery.code, delivery.fingerprint);
await delivery.receipt();


// once a year, as the floor requires
const { held } = await client.backupKey.proveShare({ code: await askForCode() });
const { held: heldByToken } = await client.backupKey.proveShare({ medium: 'token' });


// replaces a custodian. The fingerprint and every pin stay the same.
const ceremony = await allowed(await client.backupKey.replaceCustodian({ leaving: bob, joining: carol }));

A BackupKeyRegistration carries:

  • state: pending until every named custodian’s received is true, then complete
  • fingerprint: what every device pins the first time it opens a session in the tenant
  • mintedBy and mintedAt: who created the key and when
  • quorum: how many custodians must present a share together to rebuild the key

Proving a share (proveShare, which sets lastProvedAt) is a separate yearly duty that the floor requires. It does not gate completion.

A custodian’s ShareInput is either the printed code they read out, or { medium: 'token' }. The tenant uses the token form when it issued a hardware token through the offline medium adapter instead of a printed code.

What the SDK does for you

  • mint creates the key and gives each custodian their own share, as a ShareDelivery. In the same call, it signs the registration after a fresh multi-factor sign-in.
  • The SDK discards a custodian’s share from memory the moment receipt() or proveShare finishes with it. The Seald Healthcare Cloud deletes the wrapped share on receipt(). The SDK keeps only a signed commitment.
  • replaceCustodian gives the new set of custodians shares of the same key, without changing the key. The fingerprint and every device’s pin stay the same. No device needs to trust anything new.
  • Raises a custodian-share worklist item as soon as a custodian’s share is ready to collect.
  • Raises a proof-overdue worklist item when a custodian’s yearly proof is late.

Decisions and errors you may see

Outcome or ErrorCodeWhenWhat to do
deny on mintThe caller does not hold the Owner role, or named fewer than three or more than seven custodians.Ask an Owner to create the key with three to seven custodians.
fingerprint-mismatchA device’s pinned fingerprint no longer matches the registration.Do not proceed. Contact support before creating the key again.
{ held: false } from proveShareThe presented share does not match its commitment.Ask the custodian to check their offline copy, or start replaceCustodian.
challengeThe caller’s multi-factor sign-in is no longer fresh.Call stepUp(), or use the allowed helper.

Next