# Set up recovery

This guide is the how-to; see [Customer-controlled recovery](/docs/concepts/recovery) for how it
works and why it stays zero-knowledge. Recovery is org-scoped and admin-managed. All of the crypto
runs in your browser or CLI — seekrit only ever stores the recovery public key and shares it cannot
open.

## 1. Enable recovery

Choose custodians (org members who have finished [key setup](/docs/guides/web-app)) and a threshold
**M** — how many of them are required to recover.

**In the web dashboard:** Organization → **Settings** → **Customer-controlled recovery** → toggle
each custodian on, set the threshold, then **Enable recovery**. The dashboard generates and splits
the recovery key locally and immediately protects every environment you can decrypt.

**With the CLI:**

```bash
# 3-of-5 recovery: any three of these five custodians can recover.
seekrit recovery setup --threshold 3 \
  --custodian alice@example.com \
  --custodian bob@example.com \
  --custodian carol@example.com \
  --custodian dan@example.com \
  --custodian erin@example.com
# A single --custodian with --threshold 1 is the "designated recovery admin" case.
```

## 2. Cover every environment

Recovery can only protect an environment whose DEK someone wraps to the recovery key, and only a
principal that can already decrypt an environment can do that. New environments are covered
automatically at creation; to backfill the rest, each admin who holds grants runs:

```bash
seekrit recovery sync        # wraps every environment you can decrypt but that isn't yet covered
seekrit recovery status      # shows M-of-N, custodians, and coverage (e.g. "7/8 protected")
```

Repeat from other admins until coverage is complete. In the dashboard, the recovery card shows a
coverage bar and a **Sync coverage** button.

## 3. Recover access

When someone loses their passphrase or leaves, an admin runs a recovery ceremony. Start it as the
person who will end up with access (recovering for yourself is the default):

```bash
seekrit recovery request                 # prints a request id: rrq_…
# recover access for someone else instead:
seekrit recovery request --target-user newadmin@example.com
```

Each custodian then approves — unwrapping their share locally and re-wrapping it to the target:

```bash
seekrit recovery approve rrq_XXXXXXXX     # run by each custodian until the quorum is met
```

Once a quorum has approved, the target completes the ceremony — reconstructing the recovery key in
their own client and re-granting themselves access:

```bash
seekrit recovery complete rrq_XXXXXXXX    # restores access to every covered environment
```

The dashboard exposes the same flow: **Recover access** → **Start recovery**, an **Approve** button
for custodians, and **Complete** once the quorum is reached.

> **Warning:** A custodian's approval requires their passphrase (to unwrap their share) — it happens on their machine, never on a server. After a completed recovery, rotate the recovery key with `seekrit recovery rotate --threshold M --custodian …`, since it was briefly reconstructed in the clear on the target's device.

## Rotating and disabling

```bash
seekrit recovery rotate --threshold 2 --custodian alice@example.com --custodian bob@example.com
seekrit recovery disable      # removes the recovery key and every recovery grant
```

Rotation generates a fresh recovery key, re-splits it to the custodian set you pass, and re-wraps
the environments you can decrypt — run `seekrit recovery sync` from other admins afterward to
restore full coverage. Every recovery action is written to the [audit log](/docs/guides/audit-export).