Update an existing email or mobile

An authenticated user overwrites and replaces an authN ID, one that already exists on their User entity, with a new authN ID. [product: dim]

[/product: dim]

Initial Request

The Process Start API initializes the Process:

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

Response

Digital Identity Management responds with a request for authN ID information:

**RESONSE - body**
{
   "processId": "4e8c8ac0-c4f0-40cc-9dd5-08dd2e48510d",
   "processName": "userManagement.AddOrUpdateAuthnIdentifier.v1.0",
   "displayMessage": "Please input required information",
   "parameters": {
      "newAuthnIdentifier": "String",
      "oldAuthnIdentifier": "String"
   },
   "stepName": "AddOrUpdateAuthnIdentifierPrompt",
   "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`	The internal name of the step that the Process is currently on / just executed.
`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 user.
`parameters`	Object that specifies the info this Process requires to continue its task.
`newAuthnIdentifier`	The user’s desired new authN ID.
`oldAuthnIdentifier`	An existing authN ID that the user wants to replace. This field is required only in the “Update” scenario.
The user needs to provide both the `newAuthnIdentifier` value and the `oldAuthnIdentifier` value that the new one replaces.

Next Request: Replacement AuthN ID

The user provides their desired new authN ID, and the client passes it along with the old authN ID into the Process Step API.

**PUT https://\{your.url\}/process/step**
{
   "processId": "4e8c8ac0-c4f0-40cc-9dd5-08dd2e48510d",
   "parameters": {
      "newAuthnIdentifier": "john@example.com"
      "oldAuthnIdentifier": "john@mail.ca"
   }
}

`processId`	Unique identifier for the current instance of this Process.
`parameters`	Object that contains the data requested in the previous Process response.
`newAuthnIdentifier`	The user’s new authN ID (email, mobile, or alias).
`oldAuthnIdentifier`	The existing authN ID (email, mobile, or alias) that is being replaced.
Note: The new and old authN IDs must have the exact same format (i.e., the user cannot update an existing email address with a mobile number, or vice versa).

Process Complete

If the new authN ID does not match an existing authN ID already assigned to the user (or any other Digital Identity Management User ID), the Process completes its task and returns a 200 HTTP status code. The Process also sends an action token to the user through email or SMS.

**RESPONSE - body**
{
   "processId": "4e8c8ac0-c4f0-40cc-9dd5-08dd2e48510d",
   "processName": "userManagement.AddOrUpdateAuthnIdentifier.v1.0",
   "lastStep": true,
   "output": {
      "newAuthnIdentifier": {
         "id": 3,
         "status": "activating",
         "value": "john@example.com"
      },
      "oldAuthnIdentifier": {
         "value": "john@contoso.com"
      },
      "attributeName":"emails",
      "pkat": "4c6fd6cd-78a7-487d-b746-2628a77a0131"
   }
}

OTP Verification & Resend Verification Any Process that sends a Digital Identity Management action token to a user also returns a corresponding Proof key for Action Token (PKAT) to the client application. In order to enable OTP verification on the UI, the client must retain the PKAT returned in the final Process response. The PKAT, along with the user-supplied OTP, is required for the Session Token API to invoke the subsequent Activate User Process to complete the updated authN ID activation. 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 Token Resend 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 Send Verification Process for this purpose.

`processId`	The unique identifier for this instance of the 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.
`newAuthnIdentifier`	Object that contains details of the newly provisioned authN ID.
`id`	Unique identifier for the authN ID.
`status`	The authN ID’s current status.
`value`	The actual authN ID value.
`oldAuthnIdentifier`	Object that contains details of the of the authN ID to be replaced.
`attributeName`	The authN ID grouping type (`emails`, `mobiles`, or `aliases`).
`pkat`	Unique Proof Key for Action Token that corresponds to an existing action token. See action token for more details.
Note: The old authN ID remains fully activated until the user verifies the new authN ID.

Update Alias

Updating an existing alias with a new alias is identical to the Email or Mobile-based use case, except that there is no verification required for the new authN ID. If the user submits a valid alias, then Digital Identity Management immediately activates the alias, and removes the previous one. Parent topic:Add/Update Email, Mobile, or Alias Process

Home

Guides

APIs

Initial Request

Response

Next Request: Replacement AuthN ID

Process Complete

Update Alias

​Initial Request

​Response

​Next Request: Replacement AuthN ID

​Process Complete

​Update Alias

Initial Request

Response

Next Request: Replacement AuthN ID

Process Complete

Update Alias