PIN Backup API¶
Older endpoint notes
Rendered from ProjectInfo/api-docs/keyserver/backup.md on docs/encryption-modes-spec. These notes predate the REST API reference, which is canonical wherever the two overlap. They are published because they still cover endpoints the reference does not yet document — check shapes against the reference and the spec errata.
The restore endpoint is deprecated.
Accessible at /api/keys/backup/... — proxied from API to keyserver.
Lets users back up E2EE private keys encrypted with an 8-digit PIN and restore on a new device.
All endpoints require Authorization: Bearer <token>.
See e2ee.md for the full encryption procedure.
PUT /api/keys/backup¶
Create or overwrite the PIN-encrypted key backup.
Request:
{
"salt": "base64 (16 bytes)",
"encrypted_blob": "base64",
"pin_verifier": "base64",
"argon2_memory": 65536,
"argon2_iterations": 3,
"argon2_parallelism": 4,
"version": 1
}
Response 204
POST /api/keys/backup/restore¶
Restore a key backup by providing the PIN. Server checks the verifier cheaply before returning the blob.
Request:
Response 200:
{
"encrypted_blob": "base64",
"salt": "base64",
"argon2_memory": 65536,
"argon2_iterations": 3,
"argon2_parallelism": 4
}
Client must: re-derive key with full Argon2id(pin, salt, memory=65536, time=3, threads=4), then decrypt encrypted_blob with AES-256-GCM.
Errors:
- 401 — wrong PIN
- 401 with "too many attempts" — 10 failed attempts, 24-hour lockout
Show a countdown timer during lockout. After expiry, the attempt counter resets.
DELETE /api/keys/backup¶
Delete the key backup.
Response 204