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 publishsigns 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.
npx -y @shipvo/cli keys root --out root-seed.txtYou will see:
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
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| Option | Meaning |
|---|---|
--root-seed-file | The root seed file. Never the release seed. |
--new-key | Public key of the new release key. |
--sequence | A whole number above every statement you signed before. A higher number replaces a planned statement. |
--valid-from | ISO UTC time, such as 2026-11-06T00:00:00Z. Defaults to now. Up to 90 days ahead; phones reject later times. |
--json | Print 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:
npx -y @shipvo/cli audit <app> --limit 20{ "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 see | Cause | Fix |
|---|---|---|
... already exists. Not overwriting a root key. | The --out file exists | Pick 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 missing | Create the folder first. |
The root seed is not valid | The file is not a base64 32-byte seed | Use the file keys root wrote. |
--sequence must be a whole number | Missing or not a number | Pass 1, 2, 3 and so on. |
Not signed in | upload found no owner session | Run shipvo login as the owner. |
The control plane refused the statement | The sequence is not above the stored one, or no root key is registered | Raise --sequence; register the root public key. |
Next steps
- New machine and key backup for the release seed.
- CLI guide for the
--jsonenvelopes andshipvo audit. - Pointer response and rotations for the wire format.