​
Recovery Operations

When users lose their encryption context (passphrase, biometric data, etc.), you can restore wallet access using the recovery key stored during wallet creation. This process updates all key shards with a new encryption context while maintaining the same wallet address.

​
When to Use Recovery

Forgotten Passphrase

User has forgotten their original passphrase but still has access to your application.

Device Loss

User lost their device containing biometric data or other encryption context.

​
Recovery Process

The recovery operation performs the following steps:
  1. Retrieve stored recovery_key from your database
  2. Call Core API recovery endpoint with new encryption_context
  3. Update stored keys with new access_key and recovery_key
  4. Maintain the same wallet address and public key
Recovery operations update all key shards. Ensure you have proper backup procedures before initiating recovery.

​
API Reference

​
Confirm Recovery

Restore wallet access with a new encryption context using the recovery key.
cURL
curl -X POST 'https://tee.magiclabs.com/v1/api/wallet/recovery/confirm' \
  -H 'Content-Type: application/json' \
  -H 'x-magic-secret-key: sk_live_XXXXXXXX' \
  -d '{
    "wallet_id": "wallet_id",
    "encryption_context": "hashed_passcode",
    "recovery_key": "recovery_key"
  }'
Response: 
{
  "data": {
    "id": "e982b4a3-14d3-4d66-a3ac-fadfc3ae1875",
    "recovery_key": "f41c504489531934a147413865913f24",
    "access_key": "c6b2565c12a24b1e86f23e2196486541",
    "network": "ETH",
    "wallet_group_id": "58a08494-3c83-439a-8a07-551f2...",
    "metadata": {
      "resource_id": "customer-resource-id"
    },
    "time_created": 1709931542,
    "time_updated": 1809931542
  }
}

​
Request Parameters

​
wallet_id
string
required
Body
The wallet UUID returned from wallet creation.
​
encryption_context
string
required
Body
The new encryption context to be applied to the recovered wallet’s key shards.
​
recovery_key
string
required
Body
The recovery key returned from wallet creation. Retrieve from your database.

​
Response Fields

​
data.id
string
The identifier of the recovered wallet.
​
data.recovery_key
string
New recovery key for future recovery operations. Update your database with this value.
​
data.access_key
string
New access key for non-recovery operations. Update your database with this value.
Recovery operations update all key shards. Ensure you update your database with the new recovery_key and access_key values returned from this operation.