# Recover access to your workspace (/docs/guides/recovering-access)



Getting a new device into your workspace depends on what you still have. If you have at least one Authorized Device, adding another only takes an approval. If you've lost every Authorized Device, your Recovery Key is how you grant a fresh device decryption access. This guide walks through both, then shows how to verify access and rotate your key afterward.

## Before you start [#before-you-start]

You need Bowline installed on the new device and the ability to sign into your account. Beyond that, you need one of two things.

* An existing Authorized Device you can run commands on, or
* Your Recovery Key words, generated earlier with `bowline recover create`.

Signing in proves your identity, but it doesn't release workspace decryption keys on its own. One of the two above must create the grant.

## If you still have an Authorized Device [#if-you-still-have-an-authorized-device]

Approve the new device from one you already trust.

1. On the new device, run `bowline login --root ~/Code`. It authenticates your account and creates a Device Approval Request with a short matching code.
2. On an Authorized Device, run `bowline status` to see the pending request, including the device name, request age, and matching code.
3. Confirm the matching code is identical on both devices.
4. Run `bowline approve` to approve the first pending request, or `bowline approve <request>` for a specific one. Add `--yes` to skip the prompt.
5. Verify access with `bowline status` on the new device.

For more detail on this path, see [Device trust](/docs/concepts/device-trust).

## If you have lost every Authorized Device [#if-you-have-lost-every-authorized-device]

When no Authorized Device is available, use your Recovery Key to grant the new device access.

<Callout type="warn" title="You need your Recovery Key words">
  This path requires the words you stored when you ran `bowline recover create`. Without them and without an Authorized Device, you cannot recover your workspace data: the service never holds your workspace keys.
</Callout>

1. On the new device, install Bowline and run `bowline login --root ~/Code`. This authenticates your account and creates a pending Device Approval Request. Account sign-in alone does not release decryption keys.
2. Find your Recovery Key id with `bowline recover status`. Use `--json` if you're scripting.
3. Grant this device access by piping your Recovery Key words into `bowline recover use <id>`. Read them from a file to keep them out of your shell history:

   ```sh
   bowline recover use <id> < recovery-key.txt
   ```

   Bowline decrypts the recovery envelope locally, creates the pending request, publishes a self-addressed encrypted grant, accepts it, and stores the workspace key locally. The device is now an Authorized Device.

## Verify access [#verify-access]

Confirm the new device is trusted before you rely on it. Run `bowline status` on the new device and check that it reports an Authorized Device and a `healthy` status. Your projects under `~/Code` now hydrate on touch like any other trusted device.

## Rotate your Recovery Key afterward [#rotate-your-recovery-key-afterward]

Recovering with a Recovery Key means the words left their storage and passed through a command. We recommend rotating the key after every recovery so the exposed words can't be reused.

1. Run `bowline recover rotate` to generate a fresh Recovery Key and invalidate the previous envelope.
2. Store the new words somewhere safe and offline.
3. Optionally revoke the old key explicitly with `bowline recover revoke <id>`.

<Callout type="info">
  Rotate any time you suspect your Recovery Key words were exposed, not only after a recovery.
</Callout>

## Clean up lost devices [#clean-up-lost-devices]

If you recovered because devices were lost or stolen, remove their access once you're back in. Run `bowline revoke <device>` for each lost device. A revoked device loses workspace decryption authority immediately and can no longer create Work Views or leases, so it can't read your workspace if it resurfaces.

## Next steps [#next-steps]

* [Recovery keys](/docs/concepts/recovery): what a Recovery Key is and the full `bowline recover` reference.
* [Device trust](/docs/concepts/device-trust): how approval and decryption access work.
* [Add a machine](/docs/getting-started/add-a-machine): bring a new device into your workspace.
* [CLI commands](/docs/cli/commands): full reference for `bowline recover`, `approve`, and `revoke`.