> For the complete documentation index, see [llms.txt](https://docs.alignedlayer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.alignedlayer.com/wallet-as-a-service/keys-and-recovery.md).

# Keys and recovery

A passkey lives on one device and cannot be copied off it (unless the platform syncs it, for example through iCloud Keychain). So a user with a phone and a laptop needs a key on each. An account holds up to 10.

Every change to the key set is a transaction from the account itself, signed by an existing key plus Aligned's server key, except guardian recovery (below). Nothing is added or removed off chain.

## Adding a device

Two steps, on two devices.

On the **new** device, register a passkey and file a request:

```ts
const request = await aligned.keys.requestWithPasskey({ name: 'Work laptop' });
```

On a device that **already has a key**, approve it:

```ts
const [request] = await aligned.keys.listPending();
if (request) await aligned.keys.approveWithPasskey(request.id);
```

Approving prompts for the existing passkey and adds the new key on chain. Once that lands, the new device selects its key with `aligned.wallets.ensureReady` or `aligned.wallets.restore` (in React, `useActiveKey()` or `useDeviceAccess()` do it), and can sign from then on. `aligned.keys.reject(requestId)` rejects the request instead.

If registration reports `DeviceAlreadyEnrolledError`, this device already holds a passkey for the account. Call `aligned.keys.adoptExistingPasskey()` to use it rather than registering a second one.

## Listing and naming keys

```ts
await aligned.keys.listActive();          // on chain and usable
await aligned.keys.listPending();         // waiting for approval
await aligned.keys.listPendingTimelock(); // added by the guardian, still in the timelock
await aligned.keys.activeOnThisDevice();  // the subset this device can sign with

await aligned.keys.rename(keyId, 'Old phone');
```

Name every key. A user deciding which device to revoke needs a recognizable name, not a key hash.

## Removing a key

```ts
await aligned.keys.removeWithPasskey(keyHash);
```

The removal is authorized by a key other than the one being removed, so an account can never revoke its last remaining key. The prompt lists the passkeys available on this device, which is how one device revokes another.

## Deciding what to show on startup

On launch, ask whether this device can sign:

```ts
const access = await aligned.keys.ensureDeviceAccess();

switch (access.status) {
  case 'ready':        break;                  // access.activeKey is selected
  case 'no_wallet':    /* offer wallet creation */ break;
  case 'needs_device': /* offer enrollment or recovery */ break;
}
```

It selects a key silently when the device has signed before, and otherwise runs one passkey prompt to pick up a credential the platform synced here or that survived a reinstall. If it finds no usable key, `access.recovery` carries this wallet's recovery terms (whether a guardian exists, and the timelock in days) so the screen can offer the right option. Because it can prompt, call it where a prompt makes sense, such as app startup once the UI is up or an explicit retry, and not on every render. `{ adopt: false }` skips the prompt, for a background refresh or a screen that only reports state.

## Guardian recovery

For a user who has lost every device. It only works if the account was created with a guardian and a timelock.

First get a step-up proof, which is a second email code confirming the person is present:

```ts
await aligned.auth.startStepUp();
const { step_up_token } = await aligned.auth.verifyStepUp({ code });
```

Then register a passkey on the new device and start the timelocked add:

```ts
const { valid_at } = await aligned.keys.startRecoveryWithPasskey({
  chainId,
  stepUpToken: step_up_token,
});
```

The key goes on chain immediately but cannot sign until `valid_at`, which is between 1 and 14 days out depending on what the account was created with. Show that date; the wait is the security property, not a delay to work around.

During the wait, any device that still has a working key can cancel the recovery:

```ts
await aligned.keys.cancelRecovery(keyHash);
```

This is the purpose of the timelock: if someone takes over the account's email and starts a recovery, the owner has days to cancel it.
