ACCOUNT RECOVERY

The Account Recovery operation is designed to securely restore user access in cases where the primary authentication factor (e.g., face recognition + Passkey) is missing or compromised. This process leverages multi-factor verification by combining mobile phone-based identification, cryptographic Passkey presentation, and fallback Photo ID verification. It ensures that users can recover their account while preserving the privacy and integrity of biometric data through cryptographic protocols.

Operational Overview

Initial Authentication:
User completes an identity assertion using token-based methods.
Mobile Phone Entry:
User enters their registered mobile number as a recovery identifier.
FIDO Passkey Presentation:
- If available: Verified on-device using digital signatures and challenge–response checks.
- If not available: Fallback to Photo ID verification.
Fallback Photo ID Verification:
Uses biometric/document verification. Upon success, a new hardware-bound Passkey is generated.
Passkey Creation & Binding:
Newly created Passkey is securely bound to the user's account.
Confirmation & Audit Logging:
A signed audit record is created, including metadata like mobile number and timestamp.

POST/v2/account-recovery

Endpoint

POST /v2/account-recovery

Request Body

{
  "type": "ACCOUNT_RECOVERY",
  "mobilePhone": "+1234567890",
  "passkeyProvided": true,
  "passkeyData": "base64-encoded-passkey",
  "photoID": {
    "documentType": "passport",
    "documentImage": "base64-encoded-image",
    "documentNumber": "A1234567"
  },
  "redirectURL": "https://your-app.com/recovery-callback",
  "callback": {
    "url": "https://your-api.com/webhook",
    "headers": {
      "authorization": "Bearer YOUR_TOKEN"
    }
  },
  "locale": "en-US",
  "sessionExpiry": 1800,
  "transactionID": "txn-recovery-789012",
  "deviceInfo": {
    "os": "Android 12",
    "model": "Pixel 6",
    "resolution": "2400x1080"
  },
  "challenge": "unique-nonce-string",
  "debugMode": false,
   "requirements": [
      "face",
      "identity_document"
      "passkey",
    ],
}

Parameter Details

Name
type
Type
(String, Required)
Description
Must be "ACCOUNT_RECOVERY" to initiate the recovery process.
Name
mobilePhone
Type
(String, Required)
Description
The mobile number used as a recovery identifier.
Name
passkeyProvided
Type
(Boolean, Required)
Description
Set to true if user presents an existing Passkey.
Name
passkeyData
Type
(String, Optional)
Description
Base64-encoded Passkey; required if passkeyProvided is true.
Name
photoID
Type
(Object, Optional)
Description
Fallback data if Passkey is not available.
Name
documentType
Type
(String)
Description
e.g., passport or driver's license.
Name
documentImage
Type
(String)
Description
Base64-encoded image of the ID.
Name
documentNumber
Type
(String)
Description
Document identifier.
Name
redirectURL
Type
(String, Required)
Description
Where to redirect the client after recovery completes.
Name
callback
Type
(Object, Required)
Description
Asynchronous webhook details.
Name
url
Type
(String)
Description
Webhook destination URL.
Name
headers
Type
(Object)
Description
Authorization headers for secure callback.
Name
locale
Type
(String, Optional)
Description
Locale for the session (e.g., "en-US").
Name
sessionExpiry
Type
(Integer, Optional)
Description
Session expiration duration in seconds.
Name
transactionID
Type
(String, Optional)
Description
Client-generated recovery tracking ID.
Name
deviceInfo
Type
(Object, Optional)
Description
Information about the recovery device.
Name
challenge
Type
(String, Optional)
Description
Cryptographic nonce to prevent replay attacks.
Name
debugMode
Type
(Boolean, Optional)
Description
Enable verbose logging (disable in production).
Name
requirements
Type
(Array, String)
Description
Enables usage of different scenarios. Require face scan, document scan, passkey.

Webhook Response

Success

{
  "message": "Account recovery successful.",
  "status": "success",
  "sessionId": "recovery-session-abc123",
  "recoveryResult": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "passkeyStatus": "present"
  },
  "auditLog": {
    "deviceInfo": {
      "os": "Android 12",
      "model": "Pixel 6"
    },
    "timestamp": 1680000000,
    "transactionID": "txn-recovery-789012"
  }
}

Failure

{
  "status": "error",
  "message": "Account recovery failed: Invalid passkey and photo ID verification failed.",
  "errorCodes": [1, -12],
  "retryAfter": 10
}

Cryptographic Considerations

Passkey Verification: Ensures authenticity via signature validation and challenge-response pairing.
Fallback Photo ID Verification: Secure document authentication with hardware-backed key creation.
Challenge Protocol: Nonce binds request to session, protecting against replay attacks.
Data Purging: All biometric and ID data is purged post-validation. Audit logs are cryptographically signed.