custodian key

custodian key holds the two master-key lifecycle operations: replacing a vault's master key, and destroying it. Both are operator commands — be signed in with an operator token first — and both name the HTTP surface they drive at the keys API.

custodian key rotate

custodian key rotate replaces the vault's master key. It re-wraps every record and every device's copy of the key, re-locks the recovery envelope, and recomputes every token on a client_encrypted field and every blind index. Run it after the key may have been exposed.

A file stored in a file field is a client_encrypted value, so rotation recomputes its token too. It does this without fetching the file: no file is downloaded, decrypted or re-encrypted. Because the token changes, every retrieval line already sent for a file — the custodian file get <token> line — stops working and can never work again. Once the rotation completes, re-issue it: read the file's new token with custodian records get, and send a new retrieval line built from it. You do not need the original file. See retrieval lines.

You must have an enrolled device on this machine — the command unwraps the current master key through it — and, by default, the vault's existing recovery code to re-lock under.

custodian key rotate --vault acme

Options:

• --vault <slug> — the vault whose master key is being rotated (required).
• --url <api> — select the deployment.
• --resume — finish a rotation an earlier run began but did not complete, reading its state from the server.
• --abort — release the latch of an outstanding rotation and report the vault as mixed, without finishing it.
• --new-recovery-code — print a fresh recovery code instead of re-locking under the existing one, for when the code itself may have been seen.
• --yes — answer the vault-slug confirmation without prompting. It never skips the recovery-code screen.

What a rotation does before it starts

custodian key rotate prints what the rotation will invalidate, read from the deployment, and the standing warning — before anything changes:

About to rotate the master key of vault "acme". This affects, in this vault:
  - 96 tokens on client_encrypted fields (recomputed — every existing one stops resolving),
  - 12 blind indexes (all recomputed).

! Rotation changes every token on a client_encrypted field in this vault, and every blind
  index. Any token document already written — in a task attachment, a queued job, an
  agent's output — will stop resolving and must be regenerated after this completes.
! Every file in this vault is among those tokens: any retrieval line already sent for a
  file — printed or emailed — stops working and must be re-issued once this completes.
! Tokens on tokenised fields are computed by the server and are unaffected.
! Quiesce the pipeline before continuing. No other principal can read this vault while the
  rotation runs.

Unless you pass --yes, it then asks you to type the vault slug to confirm:

Type the vault slug "acme" to confirm this rotation:
>

It then asks for the vault's existing recovery code, so the new master key is re-locked under the same code you already filed:

Enter the vault's existing recovery code (the twenty-four words), so the new master key is re-locked under it:
>

Pass --new-recovery-code to print a fresh code instead. That prints the twenty-four words once, as a hard stop, and requires you to type an acknowledgement back — the same screen custodian init uses. Any recovery code an earlier run printed is then void. Even with --yes, the recovery-code screen is never skipped.

On success:

Rotation complete. 128 records re-wrapped under the new master key; every live device holds the new copy and the old copies have been deleted.

If a rotation is interrupted

A rotation that dies part-way leaves the vault mixed — some records under the new wrapping, some under the old — and says so, naming what to run:

The rotation did not finish: <reason>
40 records now carry the new wrapping and 88 still carry the old. To finish it, run
  custodian key rotate --resume
or to release the latch and leave the vault mixed (learning its state now), run
  custodian key rotate --abort

--resume reads the outstanding rotation's state from the server and finishes it; it needs no local state from the earlier run, but must run on a device that was live when the rotation began. --abort releases the latch so ordinary reads and writes resume, and reports the mixed state:

Rotation of vault "acme" suspended — the latch is released and ordinary reads and writes resume. The vault is MIXED: 40 records now carry the new wrapping and the rest still carry the old.
  Finish it with `custodian key rotate --resume`.

custodian key destroy

custodian key destroy deletes every wrapped copy of the vault's master key, clears its recovery envelope, and schedules the AWS key material for deletion. This is irreversible. Afterwards no device and no recovery code reconstructs the master key, and no client_encrypted value in the vault can ever be decrypted again — a custodian records get --reveal on such a vault fails naming the destroyed vault as the cause, and the vault can no longer take a recovery envelope.

custodian key destroy --vault acme

Options:

• --vault <slug> — the vault whose keys are being destroyed (required).
• --url <api> — select the deployment.
• --dry-run — print the pre-flight summary and destroy nothing.
• --confirm-vault <slug> — confirm non-interactively by naming the vault slug. Refused when standard input is a terminal.

The pre-flight

Before anything happens, custodian key destroy prints what will become unrecoverable, counted from the deployment, and names the two windows in which a copy still survives:

This will destroy every key for vault 'acme'.

  2 collections, 128 records, 96 client-encrypted values
  2 enrolled devices lose their wrapped copies
  the recovery envelope is deleted
  AWS key material behind the server-side layer is scheduled for deletion

After this, no device and no recovery code reconstructs the master key, and every
client-encrypted value is unrecoverable immediately. Two copies outlive the command:
the AWS key material, if a server-side key is provisioned for this vault, stays restorable by anyone with the AWS account for about 30 days after deletion is scheduled (around 2026-10-02), and
any database backup taken before now still holds a wrapped copy for about 35 days (ageing out around 2026-10-07).
The database will refuse every write, but an administrator can undo that; the master
key itself is gone, and that no administrator can undo. There is no undo and no support
path.

Pass --dry-run to stop here:

Dry run: nothing was destroyed and no destroy request was made.

Confirming

On a terminal, custodian key destroy asks you to type the vault slug:

Type the vault slug to confirm:
>

--confirm-vault <slug> is the non-interactive form, for a script. It is refused on a terminal, so an operator at a keyboard always types the slug at the prompt:

--confirm-vault is refused when standard input is a terminal; type the vault slug at the prompt instead. Nothing was destroyed.

What it reports afterwards

Destroyed every key for vault 'acme' at 2026-09-02T09:14:07Z.

  128 records across 2 collections can no longer be decrypted.

Unrecoverable now:
  No live copy of the master key remains; no device and no recovery code reconstructs it.

Copies that outlive this command:
  AWS key material becomes unrecoverable: 2026-10-02
  last database backup holding a wrapped copy ages out: 2026-10-07

What the database refuses vs. what the cryptography makes impossible:
  The database now refuses every write on this vault, which an administrator can undo.
  The master key is gone, which no administrator can undo — no client-encrypted value can be decrypted again.

Both dates are worth filing: they are the two windows in which a wrapped copy still exists somewhere. Running the command again on an already-destroyed vault reports the original outcome and destroys nothing further.

If a master-key rotation is still outstanding, destruction is refused until you clear it:

Cannot destroy the keys of vault "acme": a master-key rotation is still outstanding. Finish it with `custodian key rotate --resume`, or clear it with `custodian key rotate --abort`, then re-run. Nothing was destroyed.