Devices and pairing

Every device has its own signing key. The server knows a device only by its public key, and a new device joins only when an existing one vouches for it.

Pair a new machine

You need both machines at the same time, though not in the same place: a remote desktop or SSH session to the old machine works.

keygrant devices add      # on a device that's already in the account: shows a pairing code
keygrant pair             # on the new machine: enter the code

Both screens then show a fingerprint. Check that they match before typing yes on the old device. This is the step that stops a malicious server from pairing a device of its own. The new machine then asks for your account password once, and it’s a full device that can sync and decrypt.

The pairing code is valid for 10 minutes and works once.

Pair a phone or browser as an approver

Run keygrant devices add as above, but enter the code at app.keygrant.app instead of running keygrant pair. The browser becomes an approver: it can approve or deny requests and see secret names, never values. See Phone approver.

List devices

keygrant devices

502a-11fb-b656-cd08  cli      Edward-GT14  9c1e40d2-6a1b-4f0e-9d33-2c8f1a7b5e60  (this device)
70f7-91ef-71ed-72e1  browser  chrome-win   3a77c0e9-81d4-4b52-a6f1-0e9b2d4c7a13

Columns: fingerprint, kind (cli or browser), name, device ID.

Remove a device

keygrant devices remove 3a77          # an ID prefix is enough if it's unique

You’re asked to type remove to confirm. Removing a cli device also rotates the vault key: a fresh key is generated and every item is re-encrypted, so a lost device’s cached key no longer opens new data.

Secrets a lost machine already synced are still on that machine. If it was lost or stolen, rotate the real API keys at each provider too.

Trust approvers paired elsewhere

A CLI device only accepts verdicts from approvers it trusts. The device that paired the approver trusts it automatically; on your other machines run:

keygrant devices trust

It lists browser approvers this machine doesn’t trust yet, shows each fingerprint, and asks you to confirm it against the fingerprint on that approver’s page.