Recover user identity (multiple authN IDs)

This is similar to the standard use case delivered by the Recover ID Process, except the end user has more than one registered, verified authentication identifier (authN ID). An anonymous end user selects to recover their identity using a registered authN ID (email or mobile). In this use case, the end user actually has more than one registered and verified authN ID. Therefore, once they submit one of their authN IDs to show who they are, the Process will then return a list of obfuscated authN IDs, and request for the end user to specify where they want the reset action token to be sent.

Initial Request

Your client calls the Process Start API to initialize the Process:

**POST https://\{your.url\}/process/start/recovery.PasswordRecovery.v1.0**
<no body>

Response

Digital Identity Management responds with a request to provide a registered (and verified) email or mobile:

**RESPONSE - body**
{
   "processId": "80d248a2-ec15-428f-be42-500426fabec9",
   "processName": "recovery.PasswordRecovery.v1.0",
   "displayMessage": "Please input required information",
   "parameters": {
      "authnIdentifier": "String"
   },
   "stepName": "UsernamePrompt",
   "lastStep": false
}

`processId`	Unique identifier for the current instance of this Process.
`processName`	Full name of the Process, including the category and version number.
`stepName`	Name of the specific step that the Process is currently on.
`lastStep`	Boolean that indicates whether or not this was the last step in the Process.
`displayMessage`	Optional message that the UI can display to the end user.
`parameters`	Object that specifies the info this Process requires to continue its task.
`authnIdentifier`	One of the user’s available Authentication Identifiers, used to identify the Digital Identity Management profile.

Next Request: User’s AuthN ID

Your client calls the Process Step API, and passes the user-supplied authN ID to the Process:

**PUT https://\{your.url\}/process/step**
{
   "processId": "80d248a2-ec15-428f-be42-500426fabec9",
   "parameters": {
       "authnIdentifier": "bob@example.com"
   }
}

`processId`	Unique identifier for the current instance of this Process.
`parameters`	Object that contains the data that was requested in the previous Process response.
`authnIdentifier`	One of the user’s available Authentication Identifiers, used to identify the Digital Identity Management profile.

Response: Specify destination AuthN ID

Digital Identity Management looks up the User entity and determines that they have two or more verified contact channels registered as authN IDs on the User entity. The Process returns a list of obfuscated authN IDs and requests the end user to select which destination to which they want the recovery message sent:

**RESPONSE - body**
{
   "processId": "7260a62c-bc7e-4097-ae55-baa8dd7d1a6e",
   "processName": "recovery.PasswordReset.v1.0",
   "displayMessage": "Please input required information",
   "parameters": {
      "recoveryOptionId": "Integer"
   },
   "stepName": "NewPasswordPrompt",
   "returnParameters": {
      "recoveryOptions": {
         "0": "b**@example.com",
         "1": "9******567"
      }
   }
   "lastStep": false
}

`processId`	Unique identifier for the current instance of this Process.
`processName`	Full name of the Process, including the category and version number.
`lastStep`	Boolean that indicates whether or not this was the last step in the Process.
`parameters`	Data object that specifies the required information this Process requires to continue its task.
`recoveryOptionId`	The selected recovery option, from the list provided in the `recoveryOptions` object.
`returnParameters`	Object containing additional data that the client can retrain and use for additional operations beyond the Process.
`recoveryOptions`	Contains key-value pairings of an identifier and an obfuscated recovery option value for the user to select from.
Note: The list of available recovery options contains values which are masked for security purposes. Enough of the recovery option method should be visible so the user may identify the particular Authentication Identifier in question, but not enough such that a malicious attacker could reasonably identify or brute-force the remaining masked portion.

The recoveryOptions object should be used to display possible options to the user. The object is formatted in a key/value pairing, where the key is the index of the recovery option, and the value is the Authentication Identifier correspondent to the recovery option, which the user can identify.

Final Request

When the end user selects a destination, your client provides the index selection (from the previous Process response) to Digital Identity Management in the PUT /process/step API:

**PUT https://\{your.url\}/process/step**
{
   "processId": "7260a62c-bc7e-4097-ae55-baa8dd7d1a6e",
   "parameters": {
      "recoveryOptionId": "0"
   }
}

`processId`	Unique identifier for the current instance of this Process.
`parameters`	Data object that contains the data request in the previous Process response.
`recoveryOptionId`	The identifier of the selected recovery option.

Process Complete

Digital Identity Management issues an action token, and ends it to the contact channel specified by the end user. The Process ends, and returns a 200 HTTP status:

**RESPONSE - body**
{
   "processId": "80d248a2-ec15-428f-be42-500426fabec9",
   "processName": "recovery.PasswordRecovery.v1.0",
   "lastStep": true,
   "output": {
      "pkat": "7c72281e-deb1-430c-be59-f3e0af71174d",
      "selectedRecoveryOptionType": "EMAIL",
      "selectedRecoveryOption": "b**@example.com"
   }
}

OTP Verification & Resend Verification Any Process step that sends a Digital Identity Management action token to a user also returns a corresponding PKAT to the client application. In order to enable OTP verification on the UI, the client must retain the PKAT returned by the final Process step. The PKAT, along with the user-supplied OTP, is required for the [GET /session/token?customToken=\{OTP\}&pkat=\{pkat\}](c_sessionToken#) API to invoke the subsequent Activate User Process to complete the user onboarding. In cases where the user is anonymous, the PKAT is required if the application wants to provide a quick token resend option on the UI, using the [PUT /session/token?pkat=\{pkat\}](c_putSessionToken) API. This method applies to cases where the user is anonymous (i.e., they are not authenticated in Digital Identity Management). However, if the user is currently authenticated in Digital Identity Management, the client application can instead invoke the Resend Verification Process for this purpose.

`processId`	Unique identifier for the current instance of this Process.
`processName`	Full name of the Process, including the category and version number.
`lastStep`	Boolean that indicates whether or not this was the last step in the Process.
`output`	Object that contains data that the client can consume, retain, and use for additional operations.
`pkat`	Unique Proof Key for Action Token that corresponds to an existing action token. See Action Tokens for more details.
`selectedRecoveryOptionType`	Identifies the method (email or SMS) in which a recovery message was generated and delivered to.
`selectedRecoveryOption`	Identifies the e-mail address or phone number in which a recovery message was generated and delivered to. Sensitive data (email address / mobile number) is masked out for security concerns.
Note: Even if an invalid authN ID is supplied to the Process (no matching user exists within Digital Identity Management), the Process will respond as if a notification has been sent. This is a security measure to prevent malicious actors from brute-force attempts to read responses and determine valid authN IDs. Digital Identity Management will not try to deliver notifications to users who do not exist. Instead, the Process silently fails.

Parent topic:Recover ID & Reset Password Processes

Home

Guides

APIs

Initial Request

Response

Next Request: User’s AuthN ID

Response: Specify destination AuthN ID

Final Request

Process Complete

​Initial Request

​Response

​Next Request: User’s AuthN ID

​Response: Specify destination AuthN ID

​Final Request

​Process Complete

Initial Request

Response

Next Request: User’s AuthN ID

Response: Specify destination AuthN ID

Final Request

Process Complete