POST /v2/keyshare/recover

Retrieves encrypted keyshare backups with face verification. Supports fetching multiple keys in a single request.

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

Authentication: JWT + Face Biometric (Step-Up)

Request

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

{
  "key_ids": [
    "wallet_identifier_ecdsa",
    "wallet_identifier_eddsa"
  ],
  "face_scan": "base64_encoded_face_scan",
  "audit_trail_image": "base64_encoded_image",
  "low_quality_audit_trail_image": "base64_encoded_image",
  "user_agent": "Mozilla/5.0..."
}

Field	Type	Required	Description
`key_ids`	array	Yes	Array of MPC key/wallet identifiers to recover
`face_scan`	string	Yes	Base64-encoded face scan from FaceTec SDK
`audit_trail_image`	string	Yes	Base64-encoded high-quality audit image
`low_quality_audit_trail_image`	string	Yes	Base64-encoded low-quality audit image
`user_agent`	string	Yes	Client's user-agent (required by FaceTec)

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" }
    }
  ]
}