POST /v2/keyshare/recover

Retrieves encrypted keyshare backups after a successful face match. Supports fetching multiple keys in a single request.

Used in flow: Recovery when keyshare is lost (e.g., app reinstall, data loss)

Authentication: JWT (Access Token) with read:backup + a successful match session (step-up)

Request

Authorization: Bearer <access_token>
Content-Type: application/json

{
  "key_ids": [
    "wallet_identifier_ecdsa",
    "wallet_identifier_eddsa"
  ],
  "face_session_id": "uuid_of_successful_match_scan"
}

Field	Type	Required	Description
key_ids	array	Yes	Array of MPC key/wallet identifiers to recover
face_session_id	string	Yes	face_session_id of a match scan that completed with succeeded: true. See POST /v2/auth/face/process.

The match session is spent when this request is accepted. A second recover call needs a new scan.

Response

200 OK

{
  "success": true,
  "keyshares": [
    {
      "key_id": "wallet_identifier_ecdsa",
      "encrypted_keyshare": "base64_encoded_encrypted_data_ecdsa"
    },
    {
      "key_id": "wallet_identifier_eddsa",
      "encrypted_keyshare": "base64_encoded_encrypted_data_eddsa"
    }
  ]
}

207 Multi-Status - partial success

{
  "success": false,
  "message": "Some keyshares could not be recovered",
  "keyshares": [
    {
      "key_id": "wallet_identifier_ecdsa",
      "encrypted_keyshare": "base64_encoded_encrypted_data_ecdsa"
    },
    {
      "key_id": "wallet_identifier_eddsa",
      "error": { "code": 100301, "message": "No backup data found for this wallet" }
    }
  ]
}

400 Bad Request - face_session_id missing

{
  "error": {
    "code": 100229,
    "message": "Missing face_session_id"
  }
}

409 Conflict - session already spent, expired, or not a successful match

{
  "error": {
    "code": 100606,
    "message": "FaceTec session is no longer active"
  }
}