Skip to main content

​
User Recovery

Both Employee and Enduser user types can recover their Dfns accounts by creating recovery credentials. Employees connected with your organization are provided a recovery kit when they register on the Dfns dashboard. They should store this recovery kit securely offline. If they need to recover their account credentials, they can do so at https://app.dfns.io/recover by providing the information from the kit and a verification code proving they still have access to their email. Alternatively, an existing organization user with administrative permissions can deactivate and re-create their account using a different email address. It is possible to create as many recovery credentials as you want. Any recovery credential can be used to recover a User. Once a recovery credential is used, all the user credentials (recovery and regular) are invalidated for security reasons. The user needs to create at least one new recovery credential, this can be done during the recovery process (see Recover User). Enduser recovery can be built by Dfns clients as described below. The process is as follows:
  1. Construct the newCredential object, using the challenge obtained from either the Create Recovery Challenge endpoint.
  2. Serialize the newCredential object to JSON and then base64url-encode the resulting JSON string. This base64url-encoded string will serve as the challenge for the recovery.credentialAssertion object.
  3. Construct the recovery.credentialAssertion object, using the base64url-encoded string generated in step 2 as its challenge.
  4. Recover User: use POST /auth/recover/user to recover a user, using a recovery credential. The recovery.credentialAssertion.clientData field’s challenge must be the base64url-encoded representation of the newCredential object.
After successfully recovering the user, all of the user’s previous credentials and personal access tokens will be invalidated.

​
End User Recovery

You can decide where in your UX flow to create recovery credentials for your end users. Depending on the value of assets and the users’ ability to create credentials from multiple devices (which is recommended), you may want to make this mandatory upfront or optional later in your flow. In order to initiate recovery, however, an end-user must have credentials already registered with the system. Here are the general steps required to perform an end-user recovery:
  • Verify the identity of your user via your existing authentication methods, KYC, etc.
  • Call the Create Delegated Recovery Challenge endpoint from a service account (DfnsApiClient.auth.createDelegatedUserRecovery in the SDK).
  • Dfns generates a new registration context, so that you can create the user’s new credentials. Forward this to your user.
  • The user creates a new credential (and optional new recovery credential)
  • The user signs the new credential(s) with their existing recovery credential, and sends the new credential(s) + signature to Dfns to Recover endpoint (DfnsDelegatedApiClient.auth.createUserRecovery in the SDK)
  • Dfns verifies the signature is valid
  • Dfns archives all of the user’s current credentials (regular + recovery)
  • Dfns adds the user’s new credentials
The following diagram explains the flow to recover an end user:
⌘I