Get started

Key rotation

Create an offline root key and replace your update signing key without a new store build.

Edit on GitHub

For app owners who want a way to replace the key that signs their updates without a new store build. You will create an offline root key, pin it in your app, and sign a rotation statement when you need a new release key.

How it works

Your app trusts two keys:

  • Release key. The key shipvo publish signs updates with. It lives in .shipvo/seed.txt.
  • Root key. Kept offline. It only signs rotation statements, never updates.

A rotation statement is signed by the root key and names a new release key. Phones check the signature and switch when they next fetch the pointer. A publish token cannot make a statement.

If the root key is lost or leaked, ship a new store build with a new root key. Nothing over the air can replace it.

1. Create the root key

Run this on a machine you trust. It needs no shipvo.json.

bash
npx -y @shipvo/cli keys root --out root-seed.txt

You will see:

text
Root public key (pin this value): <base64 public key>
Root seed written to /path/root-seed.txt (mode 0600). Store it offline, in a password manager or vault, then delete this file from this machine. Anyone with it can rotate your release key.

The seed is written with owner-only permissions and never printed. The command will not overwrite an existing file. Add --json to get { ok, code: "root_created", data: { public_key, file }, next }.

2. Pin the root public key

Pass the public key to the config plugin as rootKey (base64, 32 bytes). minSequence is optional and needs rootKey. Then register the same public key with the control plane for your app (PUT /rotation/<app>/root, signed in as the owner).

Build and submit the app to the stores. Phones from this build onward accept rotations.

3. Rotate the release key

bash
npx -y @shipvo/cli keys rotate sign \
  --root-seed-file root-seed.txt \
  --new-key <new release public key> \
  --sequence 1 > rotation.json
npx -y @shipvo/cli keys rotate upload rotation.json
OptionMeaning
--root-seed-fileThe root seed file. Never the release seed.
--new-keyPublic key of the new release key.
--sequenceA whole number above every statement you signed before. A higher number replaces a planned statement.
--valid-fromISO UTC time, such as 2026-11-06T00:00:00Z. Defaults to now. Up to 90 days ahead; phones reject later times.
--jsonPrint the standard envelope. The signed statement is in data.envelope.

sign works offline. upload needs shipvo login as the app owner; tokens are refused.

See rotations in the audit log

After upload, export the audit log. Rotations show up next to publishes and rollbacks as rows with action key-rotation. The after field holds the sequence and the time the new key starts, as JSON text:

bash
npx -y @shipvo/cli audit <app> --limit 20
json
{ "action": "key-rotation", "release": null, "release_id": null, "before": null, "after": "{\"sequence\":1,\"valid_from\":\"2026-11-06T00:00:00Z\"}" }

shipvo audit uses SHIPVO_OWNER_TOKEN, or the publish token from shipvo app create.

A new rotation is the newest row, so it shows in shipvo audit <app> --limit 20 right after upload. See shipvo audit.

Troubleshooting

You seeCauseFix
... already exists. Not overwriting a root key.The --out file existsPick a new file name. Never replace a root key you still use.
Cannot write the root key file ...: the folder does not exist.The folder in --out is missingCreate the folder first.
The root seed is not validThe file is not a base64 32-byte seedUse the file keys root wrote.
--sequence must be a whole numberMissing or not a numberPass 1, 2, 3 and so on.
Not signed inupload found no owner sessionRun shipvo login as the owner.
The control plane refused the statementThe sequence is not above the stored one, or no root key is registeredRaise --sequence; register the root public key.

Next steps