Add a new device

Each device has its own key, so a lost laptop is a device problem rather than an identity problem. Pairing is two-sided: the new device publishes, a trusted device approves.

Step 1 — on the new device

tovio device enrolltovio device enroll --name work-laptop

Generates that machine's own key, keeps the secret in its keychain, and prints two public keys plus a short pairing code. This enrols nothing by itself. A device name must not contain |.

Step 2 — on a device you already trust

tovio device approve --pubsig <hex> --pubkx <hex> --code <pairing-code>tovio device approve --pubsig <hex> --pubkx <hex> --name work-laptop --code <pairing-code>

There is no bare tovio device approve <id> form. You must supply both public keys the new device printed, and the code.

Why the code exists

Approval recomputes the pairing code from the two public keys you passed and requires it to match --code. That is the whole defence against key substitution: if someone swapped in their own keys, the recomputed code will not match the one on the new device's screen, and approval is refused as TVO-IDENT-002. Read the code aloud and compare it. Do not paste it from the same channel that gave you the keys.

On a match, the device is enrolled with a signed binding and HEAD is re-sealed so it can read existing protected content. If enrolment succeeds but the re-seal does not finish, you get TVO-IDENT-003 — recoverable, and the command is safe to re-run. A malformed enrolment claim is TVO-IDENT-001 and the device is never admitted.

Managing them

tovio device listtovio device revoke <did-or-name>

device list shows each device's name, DID, principal, whether it is the root, and whether it is this machine. A fresh single-device repository lists exactly one.

This is not the hosted-Forge flow

tovio identity authorize-device and tovio identity connect are a different thing: linking a machine to a hosted-Forge account, not adding a device key to your repository identity.

tovio identity authorize-device --account <account-id>   # on an already-linked machinetovio identity connect --forge forge.example.com:8443 --code <pairing-code>tovio identity connect --forge forge.example.com:8443 --code <pairing-code> --label work-laptop

Both require an existing device's signature — a web sign-in alone can never attach a new key to your identity. Certificate pinning is always enforced; --cert overrides the default of this repository's .tovio/relay-cert.der, and there is no skip path.

Losing one

tovio device revoke <did-or-name>

Revoke immediately from another device. HEAD is re-sealed to the reduced set under a fresh key, so the lost device loses future reads while its past signatures stay attributable. Your other machines are unaffected. Revoking when you have no other enrolled device is refused as TVO-IDENT-004, fail-closed with nothing changed.

If it was your only device

You need your key backup or your recovery phrase. This is the scenario Back up your key today exists for.

Approval is required, by design

Enrolment alone grants nothing. A new device must be approved by an existing one, or you must go through recovery. Fail-closed is the point.