Recover User

POST /auth/recover/user

Recovers a user, using a recovery credential. After successfully recovering the user, all of the user's previous credentials and personal access tokens will be invalidated.

This flow requires cryptographic validation of newly created credential(s) using a recovery credential. The recovery.credentialAssertion.clientData field's challenge must be the base64url-encoded representation of the newCredential object.

The process is as follows:

1. Construct the newCredential object, using the challenge obtained from either the Create Recovery Challenge or Create Delegated Recovery Challenge API.

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.

• Request headers required. See Request Headers for more information.

• Temporary authentication token required. See Registration Headers for more information.

Required Permissions

Since this endpoint is not authenticated, the permissions apply to the application only.

Name	Conditions
Auth:Users:Create	Always Required
Auth:Types:Employee	When kind is CustomerEmployee
Auth:Types:EndUser	When kind is EndUser

Request body

recovery *	Object	a signature of the user's new credentials, using the user's recovery credential, that proves the user initiated the recovery request
recovery.kind *	String	will always be RecoveryKey
recovery.credentialAssertion *	Object
recovery.credentialAssertion.credId *	String	base64url encoded id of the recovery credential
recovery.credentialAssertion.clientData *	String	base64url encoded Client Data JSON string object that was signed with the user's private key
recovery.credentialAssertion.signature *	String	base64url encoded signature generated by signing the clientData JSON string object
newCredentials *	Object	the new credentials being assigned to the user
newCredentials.firstFactorCredential *	Object	new first factor credential that the user is registering
newCredentials.secondFactorCredential	Object	Optional new second factor credential that the user is registering
newCredentials.recoveryCredential	Object	Optional new recovery credential that can be used to recover the user's account

Fido2 Credential

credentialKind *	String	will always be Fido2
credentialInfo *	Object
credentialInfo.credId *	String	base64url encoded id of the credential
credentialInfo.clientData *	String	base64url encoded client data object. The underlying object is the clientData object returned by the user's WebAuthn client
credentialInfo.attestationData *	String	base64url encoded attestation data object. The underlying object is the attestationData object returned by the user's WebAuthn client

Example

{
  "recovery":{
    "kind":"RecoveryKey",
    "credentialAssertion":{
      "credId":"d0MjPWGaRYS4H9fpubGCMCw7mhUCu3hP3NAkRtdGNK0",
      "clientData":"eyJ0eXBlIjoia2V5LmdldCIsImNoYWxsZW5nZSI6Ik1XTTBNbVk1WVRRME1EUmlOemRoTlRGaE56WTVPRFF3TldJNVpUUTRZMlJoT0RaaU5EazNaVFl6T1RFNU9HWXlNRGN4WmpCall6azRNbVE1WXpZMU1BIiwib3JpZ2luIjoiaHR0cHM6Ly9hcHAuZGZucy5uaW5qYSIsImNyb3NzT3JpZ2luIjpmYWxzZX0",
      "signature":"b6-3t95LkFnXhL6F8MDBHdUBsrVdm9wycq9SCsJhyiHph9uaVCJw9Vb-TlO1ILLKJvmoPELyx7XjpAC9Ww65UA",
    }
  },
  "newCredentials":{
    "firstFactorCredential":{
      "credentialKind":"Fido2",
      "credentialInfo":{
        "credId":"c1QEdgnPLJargwzy3cbYKny4Q18u0hr97unXsF3DiE8",
        "clientData":"eyJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIiwiY2hhbGxlbmdlIjoiTVdNME1tWTVZVFEwTURSaU56ZGhOVEZoTnpZNU9EUXdOV0k1WlRRNFkyUmhPRFppTkRrM1pUWXpPVEU1T0dZeU1EY3haakJqWXprNE1tUTVZelkxTUEiLCJvcmlnaW4iOiJodHRwczovL2FwcC5kZm5zLm5pbmphIiwiY3Jvc3NPcmlnaW4iOmZhbHNlfQ",
        "attestationData":"WT-zFZUBbJHfBkmhzTlPf49LTn7asLeTQKhm_riCvFgFAAAAAA"
      }
    },
    "recoveryCredential":{
      "credentialKind":"RecoveryKey",
      "credentialInfo":{
        "credId":"GMkW0zlmcoMxI1OX0Z96LL_Mz7dgeu6vOH5_TOeGyNk",
        "clientData":"eyJ0eXBlIjoia2V5LmNyZWF0ZSIsImNoYWxsZW5nZSI6Ik1XTTBNbVk1WVRRME1EUmlOemRoTlRGaE56WTVPRFF3TldJNVpUUTRZMlJoT0RaaU5EazNaVFl6T1RFNU9HWXlNRGN4WmpCall6azRNbVE1WXpZMU1BIiwib3JpZ2luIjoiaHR0cHM6Ly9hcHAuZGZucy5uaW5qYSIsImNyb3NzT3JpZ2luIjpmYWxzZX0",
        "attestationData":"Wsdz5810zjVJEyEtx9jYU0dizfhIkdu9AOGl2kYtcBusAPsfjdncE6zKW8ms_VkhJ6Hw4HDfcYj5FHcdM-C4CA"
      },
      "encryptedPrivateKey":"LsXVskHYqqrKKxBC9KvqStLEmxak5Y7NaboDDlRSIW7evUJpQTT1AYvx0EsFskmriaVb3AjTCGEv7gqUKokml1USL7+dVmrUVhV+cNWtS5AorvRuZr1FMGVKFkW1pKJhFNH2e2O661UhpyXsRXzcmksA7ZN/V37ZK7ITue0gs6I="
    }
  }
}

Key Credential

credentialKind *	String	will always be Key
credentialInfo *	Object
credentialInfo.credId *	String	base64url encoded id of the credential
credentialInfo.clientData *	String	base64url encoded Client Data JSON string object that was signed with the user's private key
credentialInfo.attestationData *	String	base64url encoded Credential Attestation JSON string object with the user's signature and public key

Example

{
  "recovery":{
    "kind":"RecoveryKey",
    "credentialAssertion":{
      "credId":"d0MjPWGaRYS4H9fpubGCMCw7mhUCu3hP3NAkRtdGNK0",
      "clientData":"eyJ0eXBlIjoia2V5LmdldCIsImNoYWxsZW5nZSI6Ik1XTTBNbVk1WVRRME1EUmlOemRoTlRGaE56WTVPRFF3TldJNVpUUTRZMlJoT0RaaU5EazNaVFl6T1RFNU9HWXlNRGN4WmpCall6azRNbVE1WXpZMU1BIiwib3JpZ2luIjoiaHR0cHM6Ly9hcHAuZGZucy5uaW5qYSIsImNyb3NzT3JpZ2luIjpmYWxzZX0",
      "signature":"b6-3t95LkFnXhL6F8MDBHdUBsrVdm9wycq9SCsJhyiHph9uaVCJw9Vb-TlO1ILLKJvmoPELyx7XjpAC9Ww65UA",
    }
  },
  "newCredentials":{
    "firstFactorCredential":{
      "credentialKind":"Key",
      "credentialInfo":{
        "credId":"6Ca6tAOFTx2odyJBnCoRO-gPvfpfy0EOoOcEaxfxIOk",
        "clientData":"eyJ0eXBlIjoia2V5LmNyZWF0ZSIsImNoYWxsZW5nZSI6Ik1XTTBNbVk1WVRRME1EUmlOemRoTlRGaE56WTVPRFF3TldJNVpUUTRZMlJoT0RaaU5EazNaVFl6T1RFNU9HWXlNRGN4WmpCall6azRNbVE1WXpZMU1BIiwib3JpZ2luIjoiaHR0cHM6Ly9hcHAuZGZucy5uaW5qYSIsImNyb3NzT3JpZ2luIjpmYWxzZX0",
        "attestationData":"WT-zFZUBbJHfBkmhzTlPf49LTn7asLeTQKhm_riCvFgFAAAAAA"
      }
    },
    "recoveryCredential":{
      "credentialKind":"RecoveryKey",
      "credentialInfo":{
        "credId":"GMkW0zlmcoMxI1OX0Z96LL_Mz7dgeu6vOH5_TOeGyNk",
        "clientData":"eyJ0eXBlIjoia2V5LmNyZWF0ZSIsImNoYWxsZW5nZSI6Ik1XTTBNbVk1WVRRME1EUmlOemRoTlRGaE56WTVPRFF3TldJNVpUUTRZMlJoT0RaaU5EazNaVFl6T1RFNU9HWXlNRGN4WmpCall6azRNbVE1WXpZMU1BIiwib3JpZ2luIjoiaHR0cHM6Ly9hcHAuZGZucy5uaW5qYSIsImNyb3NzT3JpZ2luIjpmYWxzZX0",
        "attestationData":"Wsdz5810zjVJEyEtx9jYU0dizfhIkdu9AOGl2kYtcBusAPsfjdncE6zKW8ms_VkhJ6Hw4HDfcYj5FHcdM-C4CA"
      },
      "encryptedPrivateKey":"LsXVskHYqqrKKxBC9KvqStLEmxak5Y7NaboDDlRSIW7evUJpQTT1AYvx0EsFskmriaVb3AjTCGEv7gqUKokml1USL7+dVmrUVhV+cNWtS5AorvRuZr1FMGVKFkW1pKJhFNH2e2O661UhpyXsRXzcmksA7ZN/V37ZK7ITue0gs6I="
    }
  }
}

Recovery Credential

credentialKind *	String	will always be RecoveryKey
credentialInfo *	Object
credentialInfo.credId *	String	base64url encoded id of the credential
credentialInfo.clientData *	String	base64url encoded Client Data JSON string object that was signed with the user's private key
credentialInfo.attestationData *	String	base64url encoded Credential Assertion JSON string object with the user's signature and public key
encryptedPrivateKey	String	Optional encrypted private key. The user should hold the secret to decrypting this value, and that secret should never be transmitted to Dfns

Example

{
  "recovery":{
    "kind":"RecoveryKey",
    "credentialAssertion":{
      "credId":"d0MjPWGaRYS4H9fpubGCMCw7mhUCu3hP3NAkRtdGNK0",
      "clientData":"eyJ0eXBlIjoia2V5LmdldCIsImNoYWxsZW5nZSI6Ik1XTTBNbVk1WVRRME1EUmlOemRoTlRGaE56WTVPRFF3TldJNVpUUTRZMlJoT0RaaU5EazNaVFl6T1RFNU9HWXlNRGN4WmpCall6azRNbVE1WXpZMU1BIiwib3JpZ2luIjoiaHR0cHM6Ly9hcHAuZGZucy5uaW5qYSIsImNyb3NzT3JpZ2luIjpmYWxzZX0",
      "signature":"b6-3t95LkFnXhL6F8MDBHdUBsrVdm9wycq9SCsJhyiHph9uaVCJw9Vb-TlO1ILLKJvmoPELyx7XjpAC9Ww65UA",
    }
  },
  "newCredentials":{
    "firstFactorCredential":{
      "credentialKind":"Key",
      "credentialInfo":{
        "credId":"6Ca6tAOFTx2odyJBnCoRO-gPvfpfy0EOoOcEaxfxIOk",
        "clientData":"eyJ0eXBlIjoia2V5LmNyZWF0ZSIsImNoYWxsZW5nZSI6Ik1XTTBNbVk1WVRRME1EUmlOemRoTlRGaE56WTVPRFF3TldJNVpUUTRZMlJoT0RaaU5EazNaVFl6T1RFNU9HWXlNRGN4WmpCall6azRNbVE1WXpZMU1BIiwib3JpZ2luIjoiaHR0cHM6Ly9hcHAuZGZucy5uaW5qYSIsImNyb3NzT3JpZ2luIjpmYWxzZX0",
        "attestationData":"WT-zFZUBbJHfBkmhzTlPf49LTn7asLeTQKhm_riCvFgFAAAAAA"
      }
    },
    "recoveryCredential":{
      "credentialKind":"RecoveryKey",
      "credentialInfo":{
        "credId":"GMkW0zlmcoMxI1OX0Z96LL_Mz7dgeu6vOH5_TOeGyNk",
        "clientData":"eyJ0eXBlIjoia2V5LmNyZWF0ZSIsImNoYWxsZW5nZSI6Ik1XTTBNbVk1WVRRME1EUmlOemRoTlRGaE56WTVPRFF3TldJNVpUUTRZMlJoT0RaaU5EazNaVFl6T1RFNU9HWXlNRGN4WmpCall6azRNbVE1WXpZMU1BIiwib3JpZ2luIjoiaHR0cHM6Ly9hcHAuZGZucy5uaW5qYSIsImNyb3NzT3JpZ2luIjpmYWxzZX0",
        "attestationData":"Wsdz5810zjVJEyEtx9jYU0dizfhIkdu9AOGl2kYtcBusAPsfjdncE6zKW8ms_VkhJ6Hw4HDfcYj5FHcdM-C4CA"
      },
      "encryptedPrivateKey":"LsXVskHYqqrKKxBC9KvqStLEmxak5Y7NaboDDlRSIW7evUJpQTT1AYvx0EsFskmriaVb3AjTCGEv7gqUKokml1USL7+dVmrUVhV+cNWtS5AorvRuZr1FMGVKFkW1pKJhFNH2e2O661UhpyXsRXzcmksA7ZN/V37ZK7ITue0gs6I="
    }
  }
}

Responses

• See Common Errors for common errors.
• See User Recovery Errors for user recovery specific errors.

200

Success - an object describing the user

{
  "credential": {
    "uuid": "cr-34514-nip9c-8bppvgqgj28dbodrc",
    "kind": "Fido2",
    "name": "Default Credential"
  },
  "user": {
    "id": "us-2ba0h-lvp2q-8v1860pcj1bh5irf",
    "username": "[e-mail]",
    "orgId": "or-34513-nip9c-8bppvgqgj28dbodrc"
  }
}