Account Recovery

Account recovery works differently in Literal because the application server never has the user’s password or encryption keys. Literal cannot reset a password or decrypt data on behalf of a document holder.

Recovery is possible only if the account already has a recovery key backup. The client uses that recovery key to restore the old master key locally, re-protect data under a new password, and submit only encrypted updates to Literal.

Prerequisites

Recovery only works if the account already has recovery material.

During setup, the client creates:

1. Recovery key — a client-held secret the user must store safely.
2. Master key backup — the user master key encrypted with the recovery key and stored by Literal.

If either is missing, Literal cannot recover the account.

Storing The Recovery Key Safely

Best practices:

• Store the recovery key separately from the account password.
• Keep an offline copy in a physically secure location.
• Use a password manager only if it is separate from the one storing the account password.
• Keep multiple copies if losing access would be unacceptable.

What Can And Cannot Be Recovered

Recovered

• Owned documents — document keys are re-wrapped under the new master key.
• Encryption and signing keys — re-encrypted under the new master key.
• Search indexes — encrypted search tokens are preserved through token rotation.
• Organization memberships — membership records remain intact.

Not Recovered

• The old password — replaced permanently.
• Existing sessions — invalidated during recovery.
• Access tokens and derived routing tokens — rotated or regenerated under the new key material.
• Temporary access continuity — some shared or indexed access paths may be unavailable until token rotation completes.

Recovery Process

Step 1 — Fetch The Encrypted Master Key Backup

The client derives a recovery blind index from the login identifier and recovery key, then asks Literal for the encrypted master key backup. Literal receives only the blind index.

Endpoint: GET /auth/recovery

Step 2 — Restore The Old Master Key Locally

The client decrypts the master key backup using the recovery key. No API call is made.

Step 3 — Set A New Password

The client derives new authentication and master-key material from the new password. No plaintext password is sent to Literal.

Step 4 — Re-Protect Local Key Material

The client re-encrypts private keys, re-wraps document keys, regenerates recovery material, and prepares updated tokens locally. No API call is made.

Step 5 — Finalize Recovery

The client submits the new authentication record, encrypted key material, re-wrapped document keys, and recovery material. Literal updates the account atomically, invalidates old sessions, and returns a locked recovery session.

Endpoint: POST /auth/recovery

Step 6 — Unlock The Session

The client submits newly derived session and routing tokens to promote the locked session to an unlocked session.

Endpoint: POST /auth/recovery/tokens

Use the API Reference for exact request fields, response bodies, and errors across all three endpoints.

Token Rotation

During unlock, the client rotates affected blind tokens so future lookups use tokens derived from the new key material. Literal can replace old tokens with new tokens without learning the plaintext identifiers behind them.

See Blind Routing for the broader token-rotation model and the API Reference for rotation payload fields.

Troubleshooting

• If recovery material is missing, recovery is unavailable.
• If the recovery key is wrong, the client cannot decrypt the master key backup.
• If finalization fails, do not discard local recovery state until the client knows whether the server accepted the update.
• If unlock fails, the session remains locked and the user may need to retry token submission or log in again.

Related Resources

• Zero-Knowledge Model — why Literal cannot reset a password or recover keys.
• Key Hierarchy — how keys are organized and re-wrapped during recovery.
• Blind Routing — how blind tokens are rotated when key material changes.
• Getting Started — initial account setup, including recovery key generation.

Last updated on