Recovery Code And Device Approval

Three things secure a synced graph, and they do different jobs: a sign-in credential proves who you are to the server, a Graph Key encrypts each graph's content, and your Recovery Code unlocks your collection of Graph Keys on a device that has none.

	What it is	What it does	If you lose it
Sign-in credential	Your EtherPK Account session, or a Personal Access Token on a custom server	Lets the app sync. Cannot decrypt anything	Sign in again, or make a new token. Nothing is lost
Graph Key	One random key per graph, held by every member	Decrypts that graph's content	You never handle it. It lives in your key bundle
Recovery Code	One code per account, created with your keys	Unlocks all your keys on a device when no other device can vouch for it	Regenerate it from any unlocked device. With none, see Recovering access

Your keys and where they live

When you create a synced graph, your device makes a random key for it, and everything in the graph is encrypted under that key before it leaves the device. Every member holds a copy of the same key; that is what sharing a graph means. Your Graph Keys, together with the identity key used for invites, are kept in one encrypted bundle on the Sync Server, so any of your devices can fetch it. The Recovery Code is what opens the bundle. The server stores the bundle but can never open it; only your devices can.

The bundle is created the first time you need it: with your first synced graph, or at once with Sync settings > Create encryption keys. Either way EtherPK shows you the Recovery Code, a code like EPK1-XXXXX-XXXXX-XXXXX-XXXXX-XXXXXX, before anything is uploaded, because content encrypted under a key that was never saved could not be opened again.

The dialog offers Copy and Download (a small text file), and does not let you continue until you tick I have saved my Recovery Code somewhere safe. It is not shown again.

Day to day you do not need the code: a new device is unlocked by approving it from one you already use. The code is your way back in when no device is unlocked.
It covers your whole account: every synced graph, including ones you create or are invited to later. You are never asked to save a new one per graph.
Nobody, including whoever runs the server, can recover your notes for you. If you lose every unlocked device and the code, notes only you could read are gone.

Add a new device

On a new device, sign in (or add a token) so the server talks to you, then do anything that needs your keys: open a synced graph, create one, or import into synced storage. EtherPK asks you to unlock and then carries on. With no graph to open, Sync settings > Unlock keys asks the same question on its own.

The Unlock your keys dialog takes your Recovery Code, or offers approve from another device:

The new device shows a short code, like 7Q4M-KX2A, and waits.
On any device where your keys are already unlocked, a prompt appears, Approve a new device?, with a code.
Compare the two screens. If the codes match, select Approve; the new device unlocks within a couple of seconds. If they differ, or you were not setting up a device at all, select Reject: a wrong code means something between your devices tampered with the request.

Your keys travel sealed from one device to the other; the server passes the message along but cannot read it. A request expires after 10 minutes if nobody approves it.

Keys stay unlocked on each device

You unlock a device once. After that the keys stay unlocked there, in new tabs and after the browser closes. They are stored on the device itself, never on the server, and regenerating your Recovery Code does not disturb them.

On a shared or public machine, use Sync settings > Lock keys when you step away. Unlocking again is the same choice of approval or code, through Unlock keys or the next time something needs them.

Regenerate the code

Sync settings > Regenerate Recovery Code works whenever your keys are unlocked, and loses nothing. Do it if you never saved your code, or if someone may have seen it.

It shows the new code first. Your current code keeps working until you tick that you have saved the new one and select Retire old code and use this one; that is the moment the new code takes over and the old one stops working for good. Keep current code backs out with nothing changed. Exactly one code is valid at any time, and devices already unlocked carry on without noticing.

Recovering access

The options run from "nothing lost" to "start over", depending on what you still have.

You did not save the code, but a device is still unlocked

Nothing is lost. Regenerate Recovery Code on that device, as above, and save the new one.

A device says a graph is not in this browser

A device can lose track of a synced graph it had before: the browser cleared its storage to make room, or you signed in to a different account on that device at some point. Your notes are safe on the server; the device only needs telling about the graph again.

Usually it tells itself. EtherPK keeps a small copy on each device of which synced graphs and passkeys belong there, in a part of browser storage that phones are far less keen to clear. When a browser has dropped the rest, the next load puts them back and says so, with a notice headed "Your browser cleared some of EtherPK's data on this device to free up space" listing what was restored. Your graphs are listed, your passkeys still work, and each graph's documents download again from the server the next time you open it. Dismiss the notice when you have read it. If a device does this often, install EtherPK as an app (Installing EtherPK As An App), and check Sync settings > Storage on this device, which says whether the browser has agreed to keep EtherPK's data.

If the notice does not appear and a graph is still missing:

Opening the graph's link shows "This graph is on your account but not set up in this browser" with Set it up here. Select it; the graph is registered and opens, after asking you to unlock if your keys are locked here.
The Knowledge graphs page offers the same: the graph appears under Synced graphs as Not on this device, with Add to this device.
If the graph opens but will not read your notes, the keys held on this device are stale. Sync settings > Lock keys, then Unlock keys, replaces them. Nothing is lost.

Reset encryption keys does not help here and deletes the graphs you own. Leave Regenerate Recovery Code alone until you are back in, because it retires the code you are holding.

If the notice instead says the graph was set up under a different sync account, this device is connected as an account that is not a member of it. Connect the other account in Sync settings, or ask the graph's owner to invite the one you are using.

You are locked out

With no unlocked device and no Recovery Code, you cannot decrypt your notes, and two options remain:

Rescue shared graphs by handing them over. Any graph you own that has other players can be transferred to one of them, from the Synced graphs panel or from inside Reset encryption keys. The graph stays alive under their ownership, and they can invite your new identity back later. This needs no keys, so it works even though you are locked out.
Graphs that are yours alone cannot be rescued. If you were the only person holding a graph's key, no one can recover it. The reset dialog says which graphs these are.

Start over

Sync settings > Reset encryption keys is the deliberate clean slate. It:

deletes every graph you own (transfer the shared ones first if you want to keep them);
removes you from graphs other people own, which are untouched;
leaves the account with no keys, so the next thing that needs them creates a fresh identity and Recovery Code. Create encryption keys does that straight away.

The dialog first lists what would be deleted and offers Transfer… for each shared graph. It then asks you to type the damage to confirm, DELETE 2 GRAPHS with the real number, or RESET MY KEYS if you own none, and cannot be undone. If it cannot read the list of what would be deleted, it refuses to continue rather than guess.

Quick reference

Situation	Do this
Setting up a new device while another is unlocked	Approve from another device; no code needed
Skipped saving the code, but a device is unlocked	Regenerate Recovery Code there; nothing lost
Want a fresh code	Regenerate Recovery Code; nothing lost
A graph says it is not in this browser	Set it up here or Add to this device
A graph opens but will not read your notes	Lock keys, then Unlock keys
Access token lost or exposed	Revoke it in the portal and create a new one; notes unaffected
Locked out, graph is shared	Transfer the graph to a player, then reset
Locked out, graph is yours alone	Unrecoverable; reset to start over

Not to be confused with

The protection passphrase for Protected Documents is separate. The Recovery Code does not recover it, and it does not recover the Recovery Code.
Your EtherPK Account password signs you in to the server. Resetting it changes nothing about your keys (Your EtherPK Account).