Recovering after losing your identity key

Losing your identity key is not automatically the end of your access. Which path applies depends on what you still have, and the two are not interchangeable.

Two different commands

How recovery works

When init creates a cryptographic identity, it also generates an independent recovery key and enrolls it as an additional recipient of protected content. That is what makes recovery possible without your identity key: the content was already wrapped to a second key you hold separately.

tovio key recover --from <file>

It uses that key to re-wrap the current head’s content keys to a freshly generated identity.

Which repositories have one

Only the ones that have an identity at all — a repository initialized with --mode team or --mode agentic. A Simple repository has no cryptographic identity, no protected content, and therefore no recovery key: there is nothing for it to recover, and asking it to recover is one of the ways TVO-KEY-006 fires.

tovio identity show

If that reports no identity, you are in a Simple repository and this article does not apply to you.

When it refuses

TVO-KEY-006 covers every failure here, and it fails closed — no fresh identity is installed and nothing is re-wrapped, so a wrong or corrupt phrase can never silently install an unrelated key. The causes:

• The file could not be read.
• The phrase is not 64 hexadecimal characters.
• It is not this repository’s recovery key.
• The repository has no recovery key on record at all — a Simple repository, or one created before recovery existed.

Try your colleagues first

Recovery re-wraps content to a brand-new identity, which is a bigger hammer than you often need. If other people are enrolled on the content, the simpler answer is to generate a new identity normally and have one of them re-enrol you. Ask before reaching for the recovery phrase — and if you are the only recipient, recovery is the path.

If there is genuinely no path back

No key, no backup, no recovery phrase, and no other recipient means the protected content is unrecoverable. That is the honest answer and it is a property of the design, not a bug — there is no vendor-side escrow to appeal to.

Do this before you need it

tovio key export <file> --passphrase-file <file>

tovio key status

The passphrase is read from a file rather than an argument so it never lands in argv, shell history, or logs.

Store the recovery phrase somewhere separate from the machine holding the key. A backup on the same disk as the thing it protects is not a backup.

Reporting it

The code and which of the four causes above applies. Never paste a recovery phrase, a backup file, or a passphrase — anywhere, to anyone, including support.