Recovery keys

A Recovery Key is generated, word-based recovery material that can grant a new device workspace decryption access when you have no other Authorized Device to approve it. Bowline generates the words, and you store them outside the service. A Recovery Key is never a passphrase you choose, and the service never holds your workspace keys in plaintext. This page explains what a Recovery Key is, when you need one, and how the bowline recover subcommands work.

What a Recovery Key is

A Recovery Key is a generated 24-word key. The words decrypt a recovery envelope locally on your device, and Bowline then runs the same device approval path it uses for a normal Authorized Device. The control plane stores only the encrypted envelope and grant ciphertext, never the Recovery Key words or your plaintext workspace key.

• Bowline generates it. You don't pick the words, so they're not a guessable passphrase.
• You store it outside the service. Keep the words somewhere safe and offline, such as a password manager or a printed copy.
• It's the fallback path. An existing Authorized Device is the normal way to grant access; a Recovery Key is for when you have none.

When you need one

A Recovery Key matters in exactly one situation: you need to grant a new device decryption access and you have no other Authorized Device to do it. For example:

• You lost, wiped, or replaced every machine that was an Authorized Device.
• All your devices are unavailable at once, and you need access from a fresh one.

When you still have at least one Authorized Device, you don't need a Recovery Key. Approve the new device instead, as described in Device trust.

The bowline recover subcommands

The bowline recover command (aliased as bowline recovery) creates, inspects, and uses Recovery Keys. Each subcommand accepts --json for scriptable output.

Reading the words from stdin

bowline recover verify and bowline recover use read the Recovery Key words from standard input rather than from a command-line flag. This keeps the secret words out of your shell history, process arguments, and logs.

Pipe the words in, or redirect them from a file:

# From a file holding the 24 words
bowline recover use <id> < recovery-key.txt

# Or pipe them directly
echo "<your 24 recovery words>" | bowline recover verify <id>

Both verify and use reject the --idempotency-key flag. An idempotency key lets you retry a request safely by replaying it without creating a duplicate. Replaying a recovery request would mean re-presenting your secret words, so Bowline treats every verify and use invocation as a single, one-time, secret-bearing action and refuses an idempotency key on these subcommands.

Relationship to device trust

A Recovery Key and an existing Authorized Device are the two ways a new device can earn workspace decryption access. They converge on the same trust path.

When you run bowline recover use <id>, Bowline decrypts the recovery envelope locally, creates the same kind of pending Device Approval Request a normal device uses, publishes a self-addressed encrypted grant, accepts it, and stores the workspace key locally. The result is a fully Authorized Device, with the same encrypted grant and audit trail as a device approved by another device.

Next steps

• Recover access to your workspace: step-by-step recovery using a Recovery Key.
• Device trust: how approval and decryption access work.
• Status and health: where Recovery Key and device trust state appear.
• CLI commands: full reference for bowline recover.