Reshare a vault

Change a vault's signers, signing power, or threshold, and replace a signer, without changing its keys

A reshare changes who can sign for a vault. Use it to add or remove signers, change their signing power, change the threshold, or replace a signer. The vault keeps its public keys and addresses, so its assets don't move.

Before you begin

  • The vault must be active, and have no other reshare in progress.
  • Every signer you add must already be registered in your organisation. See Signers.
  • Have the signers you need ready to approve. See Who approves a reshare.
  • Your io.sign API URL, and a token that can create reshares for the vault. See Authentication.

Create a reshare

  1. Get the vault's current signers and their signing power with GET /v2/vaults/{vaultId}/signers.

  2. Send POST /v2/vaults/{vaultId}/reshares with the complete set of signers the vault should have afterwards, and the new threshold:

    {
      "threshold": 2,
      "signers": [
        { "id": "<SIGNER_ID_1>", "signingPower": 1 },
        { "id": "<SIGNER_ID_2>", "signingPower": 1 },
        { "id": "<SIGNER_ID_3>", "signingPower": 1 }
      ],
      "memo": "Add the operations team's Virtual Signer"
    }
FieldDescription
thresholdThe signing power needed to sign after the reshare. At least 2.
signersEvery signer the vault should have afterwards. Leave a signer out to remove it. id takes the signer's ID or external ID.
signers[].signingPowerAt least 1, and no more than the threshold.
expiresAtOptional. When the reshare expires if it isn't complete. Must be between 30 seconds and 24 hours away.
memoOptional. A note of up to 500 characters.

The combined signing power of the new signers must be at least the threshold. The reshare must change something: io.sign rejects a request that keeps the same signers, signing power, and threshold.

Before you send it, check which combinations of signers can meet the new threshold. See Vaults, signers, and thresholds.

Who approves a reshare

A reshare needs more approvals than a signature:

  • Every signer you keep or add must approve it, and take part while the new key shares are created.
  • Signers you remove must also approve and take part if the signers you keep don't have enough of the vault's current signing power to meet its current threshold.

If any required signer rejects the reshare, it doesn't go ahead.

To see who still needs to approve, send GET /v2/vaults/{vaultId}/reshares/{id}?include=party. The party field lists each signer with its previous and new signing power, whether it's added, removed, or kept, and its vote.

Track the reshare

Read the reshare with GET /v2/vaults/{vaultId}/reshares/{id} until it reaches a final status, or subscribe to reshare.* webhooks.

StatusMeaning
votingWaiting for signers to approve.
signingSigners are creating the new key shares.
completedFinal. The vault now has the new signers and threshold.
rejectedFinal. A required signer rejected the reshare.
failedFinal. The reshare failed. errors says why.
expiredFinal. The reshare didn't complete before expiresAt.
cancelledFinal. The reshare was cancelled.

To cancel a reshare that hasn't completed, send POST /v2/vaults/{vaultId}/reshares/{id}/cancel.

Until the reshare completes, the vault keeps its current signers and threshold.

After the reshare

❗️

Back up every signer in the vault again as soon as the reshare completes. A backup taken before the reshare may not recover the vault. See Disaster recovery process.

A removed signer can no longer sign for the vault.

Replace a signer

Replace a signer when its device is lost or retired, or when a Virtual Signer must change its sealed configuration, such as its disaster recovery key.

  1. Register the new signer. For a Mobile Signer, set up the app on the new device. For a Virtual Signer, deploy a new one with its own name and configuration. See Signers.
  2. Reshare each vault the old signer belongs to. List the new signer in place of the old one, usually with the same signing power. Leave the old signer out.
  3. Wait for each reshare to complete, then back up the vault's signers.
  4. Archive the old signer with POST /v2/signers/{signerKey}/archive. Archiving removes it from your list of signers, but doesn't remove it from any vault: do this only after every reshare is complete.

If the old signer is unavailable, make sure the signers you keep have enough of the vault's current signing power to meet its current threshold. Otherwise the reshare needs the old signer's approval, and you need disaster recovery instead.

To move a Mobile Signer to a new device without a reshare, restore its backup on the new device instead. See Mobile Signer.


Did this page help you?