POST /v2/auth/devices/register-and-recover

Registers a new device and returns the user's encrypted keyshare backups in one call.

Restoring a wallet on a new device is one action for the user but two face-gated operations for auth-svc. A match session can be spent only once, so doing it as two requests would cost two face scans. This endpoint spends one session and performs both.

Used in flow: Wallet restore on a new device after app reinstall or device switch

Authentication: JWT (Access Token) with write:devices and read:backup + Device Signature + a successful match session

Request

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

{
  "device_id": "<hex>",
  "signature": "<hex>",
  "face_session_id": "uuid_of_successful_match_scan",
  "key_ids": [
    "wallet_identifier_ecdsa",
    "wallet_identifier_eddsa"
  ]
}

Field	Type	Required	Description
device_id	string	Yes	Hex-encoded uncompressed device public key (04 || X || Y)
signature	string	Yes	Hex-encoded DER ECDSA P-256 signature. Generated the same way as for POST /auth/devices/register.
face_session_id	string	Yes	face_session_id of a match scan that completed with succeeded: true. See POST /v2/auth/face/process.
key_ids	array	Yes	Array of MPC key/wallet identifiers to recover

The challenge and device signature are checked before the match session is spent. A stale challenge, a bad signature, or a conflicting device key is rejected with the session still usable, so the app can retry without a new face scan. A registration failure returns before any keyshare is read.

Response

The response has the same shape as POST /v2/keyshare/recover.

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

A 207 response means that device registration succeeded, but at least one requested keyshare was not returned. Handle each keyshares entry individually. The match session has been spent, so any later recovery attempt requires a new successful match.

400 - face_session_id missing

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

409 - device owned by different user

{
  "error": {
    "code": 100603,
    "message": "Device already registered"
  }
}

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

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