---
title: Recovery Keys
description: Understand the organization recovery key, imported repositories, and custom repository passwords
---

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

<Callout type="warn">
  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.
</Callout>

## 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:

1. If the repository is imported **and** has a stored custom password, use that custom password.
2. 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.

## Related docs

- [Repositories](/docs/concepts/repositories)
- [Repository maintenance and status](/docs/guides/repository-maintenance)

import { Callout } from "fumadocs-ui/components/callout";
