Recovery Keys | Zerobyte Docs

Zerobyte separates account authentication from Restic repository encryption. Your login password, your organization's recovery key, any imported repository password, and APP_SECRET all serve different purposes.

The important secrets in Zerobyte

Secret	What it is for	Where it applies	Downloadable from the UI?
User password	Signing in to Zerobyte and confirming sensitive actions	Your user account	No
Recovery key (`restic.pass`)	Opening repositories that use the organization's default Restic password	The active organization	Yes, for org owners and admins after password re-authentication
Custom repository password	Opening an imported repository that uses a different Restic password	One imported repository	No separate download flow
`APP_SECRET`	Encrypting secrets that Zerobyte stores in the database	The application deployment	No

What the recovery key actually is

The downloaded restic.pass file contains the Restic password for the active organization.

That organization-level password is what Zerobyte uses when it:

Initializes a brand-new repository from the UI
Accesses a repository that relies on the organization's default password
Runs normal backup, restore, snapshot, doctor, and stats operations for those repositories

Store the recovery key outside Zerobyte in a password manager, secret vault, or other encrypted storage. If you lose both server access and the correct Restic password, your backups are not recoverable.

First-run behavior for local users

During first-run onboarding, the first local admin is created with a flag indicating they have not downloaded the recovery key yet.

Until that flag is cleared, Zerobyte redirects the user to /download-recovery-key instead of the normal app pages.

When the user downloads the file successfully:

Zerobyte verifies the user's current password
The response returns the plaintext restic.pass file
Zerobyte marks that user as having downloaded the recovery key

After that, future logins go straight to the app.

SSO behavior

SSO-created users are marked as having already downloaded the recovery key, so they are not forced through the recovery-key download screen during first login.

That means SSO rollouts should treat recovery key storage as an organization-admin responsibility. Ordinary SSO users are not individually prompted to save the key.

Who can download the recovery key

The current download endpoint requires all of the following:

You are signed in
Your active organization role is admin or owner
You re-enter your current account password

The downloaded filename is restic.pass.

New repositories vs imported repositories

Repository scenario	Password Zerobyte uses	What to choose in the UI
New repository created in Zerobyte	The active organization's recovery key	No extra password choice is shown
Existing repository that already uses the active organization's recovery key	The active organization's recovery key	`Import existing repository` + `Use the existing recovery key`
Existing repository created elsewhere with a different Restic password	A per-repository custom password	`Import existing repository` + `Enter password manually`

Important limitation

The custom password option only exists when Import existing repository is enabled. Brand-new repositories created by Zerobyte always use the active organization's recovery key.

How Zerobyte decides which password to use

Zerobyte's runtime password selection is simple:

If the repository is imported and has a stored custom password, use that custom password.
Otherwise, use the active organization's recovery key.

This has an important consequence: downloading the organization recovery key will not help with an imported repository that is configured with its own custom password.

Choosing the right import option

Choose Use the existing recovery key only when the repository already uses the same Restic password as the active organization.

Typical examples:

A repository previously created by the same Zerobyte organization
A migrated environment where the organization password was preserved

Choose Enter password manually when the repository was initialized outside this organization, for example:

A repository created with the Restic CLI
A repository created by another Zerobyte organization
A repository created by another tool that happened to use Restic

Practical guidance

Keep a secure inventory of which imported repositories use custom passwords.
Do not assume all repositories in the same Zerobyte instance share the same password model.
If you manage multiple organizations, remember that the downloaded recovery key is for the active organization.
Test restores using the same password model the repository actually uses.
Treat APP_SECRET and the recovery key as separate operational secrets. Losing one is not the same as losing the other.

On this page