Identity recovery API

Use the identity recovery API when an integration needs to help an Identity manager recover a user's wallet access. Recovery creates replacement wallet and identity records, moves the user's active identity to the new wallet path, and reports token recovery progress through a workflow status endpoint.

Identity recovery is an operator action for lost or compromised wallet access. It is not a general token transfer API, custody service, or claim migration tool.

Trusted issuers may need to issue new claims for the recovered identity after the workflow completes.

Endpoints

The identity recovery API exposes three endpoints:

Preview and execute require a caller with the Identity manager recovery permission. Status polling is available to callers with that permission and to the caller that initiated the recovery workflow in the same active organisation.

Preview recovery impact

Call the preview endpoint before submitting recovery. If you know the lost wallet address, pass it as the optional wallet query parameter.

When the request omits wallet, DALP uses the user's personal identity wallet.

curl --globoff "$DALP_API_URL/api/v2/identity-recoveries/user_123/preview?wallet=0x1000000000000000000000000000000000000001" \
  --header "X-Api-Key: $DALP_API_TOKEN"

The response shows the user, the wallet being recovered, the current identity status, token balances that need recovery, and blocking reasons when recovery cannot proceed.

{
  "data": {
    "user": {
      "id": "user_123",
      "email": "[email protected]",
      "name": "Platform operator"
    },
    "lostWallet": "0x1000000000000000000000000000000000000001",
    "identity": {
      "id": "0x2000000000000000000000000000000000000002",
      "status": "registered",
      "isMarkedAsLost": false
    },
    "tokenBalances": [
      {
        "tokenAddress": "0x3000000000000000000000000000000000000003",
        "tokenName": "Example Bond",
        "tokenSymbol": "EXB",
        "balance": "10.5",
        "balanceExact": "10500000000000000000",
        "decimals": 18
      }
    ],
    "canRecover": true,
    "blockingReasons": []
  }
}

Do not execute recovery when canRecover is false. Resolve the listed blocking reasons first.

Submit recovery

Submit recovery with the userId and, when needed, the specific lost wallet address. The executing administrator may also need to provide wallet verification.

curl "$DALP_API_URL/api/v2/identity-recoveries" \
  --request POST \
  --header "X-Api-Key: $DALP_API_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Prefer: respond-async" \
  --data '{
    "userId": "user_123",
    "wallet": "0x1000000000000000000000000000000000000001"
  }'

With Prefer: respond-async, a successful response means DALP accepted the workflow request. Use the returned statusUrl to track the transaction request. Continue to use the identity recovery status endpoint to track recovery phases.

{
  "transactionId": "txreq_123",
  "status": "QUEUED",
  "statusUrl": "/api/v2/transaction-requests/txreq_123"
}

Without Prefer: respond-async, the request starts in synchronous mode. If the recovery finishes within the wait window, DALP returns the standard mutation envelope.

{
  "data": {
    "success": true
  },
  "meta": {
    "txHashes": []
  },
  "links": {
    "self": "/v2/identity-recoveries"
  }
}

Long-running recoveries can still continue asynchronously. If the synchronous wait times out, DALP returns the same accepted workflow shape as an explicit async request. Treat both response shapes as valid and poll the returned statusUrl, then use the identity recovery status endpoint for recovery phases.

Poll recovery status

Poll the status endpoint until the workflow reaches completed, completed-with-token-failures, or failed.

curl "$DALP_API_URL/api/v2/identity-recoveries/user_123/status" \
  --header "X-Api-Key: $DALP_API_TOKEN"

The status response includes the current phase, token progress, the replacement wallet and identity when available, and a per-token failure manifest when recovery finished with token-level failures.

{
  "data": {
    "phase": "completed-with-token-failures",
    "tokensRecovered": 2,
    "totalTokens": 3,
    "error": null,
    "newWallet": "0x4000000000000000000000000000000000000004",
    "newIdentity": "0x5000000000000000000000000000000000000005",
    "tokenRecoveryFailures": [
      {
        "tokenAddress": "0x3000000000000000000000000000000000000003",
        "holderAddress": "0x1000000000000000000000000000000000000001",
        "reason": "TOKEN_PAUSED",
        "message": "Token recovery failed because the token is paused.",
        "rawError": "execution reverted"
      }
    ]
  }
}

Treat completed-with-token-failures as a partial success. The identity recovery link is in place, but the listed token balances still need operator follow-up. Typical token failure reasons are TOKEN_PAUSED, MISSING_CUSTODIAN_ROLE, NO_TOKENS, RPC_ERROR, and UNKNOWN.

Operational notes

• Use preview first so operators can see the affected wallet, identity status, balances, and blockers before submitting recovery.
• Poll status after submit; the execute endpoint returns after the workflow is accepted.
• Recheck identity and claim state after completion. KYC claims do not migrate automatically to the replacement identity.
• A missing active workflow returns a not-found response to authorised callers. Unauthorised callers receive an authorisation error instead of a workflow existence signal.

Related

• API reference
• Error handling
• User management