Reference

Key rotation

Rotation is how you change who can read new entries. Remove a teammate, replace a partner, or freshen a group on a schedule. One command does it.

What rotation does

When you rotate a group, the vault generates a new key for that group and hands it only to the readers still on your list. From the next entry onward, anyone you removed sees ciphertext again. Entries written before the rotation stay readable to whoever had access at the time.

When to rotate

A teammate leaves. An API partner changes. A laptop is lost. A quarterly hygiene pass. You do not need a reason, you just need the name of the group.

The CLI

  1. Add or remove a reader

    Edit tn.yaml directly, or use the CLI to avoid a merge mistake.

    # add a reader to a group
$ tn readers add payments did:key:z6MkPartnerAcme...

# remove a reader
$ tn readers remove payments did:key:z6MkFormerEmployee...

  2. Rotate the group

    One command. The vault mints a new group key and stages it for every reader still on the list.

    # rotate the payments group
$ tn rotate payments

# rotate every group that has membership changes
$ tn rotate --all-changed

# dry run: show what would change
$ tn rotate payments --dry-run

  3. Your readers sync

    Each remaining reader pulls their new key on the next tn wallet sync. No manual distribution, no email attachments, no chat messages with secrets.

    # on the reader's machine
$ tn wallet sync
// picked up 1 new key for group "payments"

  4. Verify (optional)

    Confirm the rotation took and inspect the active reader list.

    # show the current members of a group
$ tn readers list payments

# show the rotation history
$ tn rotate history payments

What removed readers see

They can still authenticate to the vault. They can still read entries they already had keys for. What they cannot do is decrypt anything written after the rotation. Their pickup area shows nothing new for this group.

Scheduled rotations

For hygiene, you can rotate on a schedule whether the membership changed or not. The vault accepts a cron-ish expression in tn.yaml per group. 

# tn.yaml
groups:
  payments:
    rotate_schedule: "@monthly"
    recipients:
      - did:key:z6MkPublisher...
      - did:key:z6MkFinanceTeam...
One thing to know

Rotation does not scramble records the removed reader has already decrypted. If you need that, you have to ask them to delete the copies they hold. Rotation is about the future of the log, not the past.

Further reading

← Back to the vault