Update or Change Email/Mobile

In the cidaas application, the ability to change email or mobile number is of utmost importance for users. This functionality allows users to update their contact information, ensuring accurate and up-to-date communication channels between the application and its users.

The change or update of email or mobile number with cidaas ensures users have a seamless user experience.

Securely changing email or mobile numbers is vital for cidaas. Accountability is ensured by confirming and verifying the new contact information before it is accepted.

Scenario	Description
Instant Communication Medium Change	When a user updates their account information, an email and mobile number can be updated. Thereby the values are instantly applied to their user account.
Enforce Verification before Communication Medium Change	Nowadays it is usual to carry out a verification before updating the email or mobile number. This ensures that the newly entered number also belongs to the user. It is thus directly verified and prevents typing errors, for example
Administrative Communication Medium Change via Link	Administrators can initiate communication medium changes for users through a secure link-based verification process. This allows support teams to help users update their contact information while maintaining security through user confirmation.
Communication Medium Change During Verification (trackId)	Users can change their email or mobile number during the login or registration verification process using a trackId. This allows users to correct typos or update contact information before completing verification.

Let's see the process.

Enforce Verification before Communication Medium Change

The below section will focus on how to enforce a verification using One-Time-Passwords before changing the communication medium.

How to change the email or mobile number?

1. Log in to your user profile.

2. Click on the settings icon of your user profile.

   

3. Enter all the relevant information of the new account.

   

4. Enter the verification code sent to your email ID.

   

   Once the verification code is successfully entered and verified, the email update process is initiated.

5. Once verified, your email is updated or changed to the new one.

Technical integration: Implement your Profile Page

The technical integration process involves loading the user's current data, initiating the change request (which triggers an OTP code), and validating the code entered by the user.

API	Description	Link
GET User Info	Allows retrieval of user information for their own profile	Link to API
Change or update email or mobile number	Initiates or validates the communication medium change	Link to API

---

Step 1: Load User Data

First, you need to load the user's existing profile data to pre-populate the edit form on your user profile page.

// Call GET /user-srv/userInfo using the user's Access Token
this.cidaas.getUserInfo().then(function(userInfo) {
  // Populate UI with userInfo.email and userInfo.mobile_number
});

---

Step 2: Initiate the Communication Medium Change

When the user enters a new email address or mobile number and submits the edit form, trigger the initiation API by calling the communication medium endpoint with action=initiate and passing the user's sub as a path parameter.

let payload = {
  medium: this.data.fieldKey, // "email" or "mobile_number"
  value: newValue,           // The new email or mobile number
  sub: this.userInfo.sub,
  provider: this.userInfo.provider
};

// PUT /useractions-srv/communication/medium/{sub}?action=initiate
http.put(
  `${this.baseUrl}/useractions-srv/communication/medium/${this.userInfo.sub}?action=initiate`, 
  payload, 
  { headers: getHeaders() }
);

:::info Email/SMS Template Triggered Initiating the change triggers an OTP code to the new email address or mobile number. The template VERIFY_USER is used to format the OTP message. :::

---

Step 3: Handle Verification Code Entry

Prompt the user to enter the verification code sent to their new contact address. Present a verification form or modal to capture this OTP code.

---

Step 4: Verify the OTP and Complete the Change

Call the same endpoint with action=validate to submit the verification code. If successful, cidaas applies the new value to the user profile.

let payload = {
  code: enteredCode,         // The OTP code entered by the user
  medium: this.data.fieldKey, // "email" or "mobile_number"
  value: newValue,           // The new email or mobile number
  sub: this.userInfo.sub,
  provider: this.userInfo.provider
};

// PUT /useractions-srv/communication/medium/{sub}?action=validate
http.put(
  `${this.baseUrl}/useractions-srv/communication/medium/${this.userInfo.sub}?action=validate`, 
  payload, 
  { headers: getHeaders() }
);

:::info Notification & Webhook Triggers

• Template Triggered: After successful validation, the template NOTIFY_COMMUNICATION_CHANGE is sent to the old email address or mobile number to notify the user of the update.
• Webhook Triggered: An EMAIL_CHANGED fact event is automatically generated and sent to your configured webhooks (emails only). :::

---

Email Templates

Two templates are automatically triggered during this flow:

Template Key	Description	When Sent	Recipient	Variables
VERIFY_USER	Sends OTP verification code to the new address.	During initiate action	New email/mobile	{{code}}, {{name}}, {{account_name}}
NOTIFY_COMMUNICATION_CHANGE	Notifies the old address of the change.	After successful validate action	Old email/mobile	{{communication_medium_value}}, {{name}}, {{account_name}}, {{communication_medium_name}}

Template Details

• VERIFY_USER Template:
  • Purpose: Verify control of the new email address or mobile number.
  • Trigger: When action=initiate is called.
  • Processing Type: CODE (OTP).
• NOTIFY_COMMUNICATION_CHANGE Template:
  • Purpose: Alert the user of profile changes to protect against account takeover.
  • Trigger: After successful action=validate.
  • Note: Only sent if the old communication medium exists and was verified.

---

Webhooks and Facts

When a communication medium is successfully changed, cidaas generates webhook events:

Event Type	Object Type	Object ID	Description	Webhook Attributes
EMAIL_CHANGED	users	sub	Email address was changed	For instant change: ["identity_id", "sub"] For verified change: ["email", "email_verified"]
COMMUNICATION_MEDIUM_CHANGE	users	sub	Email or mobile changed by admin and confirmed by user	["medium", "value", "verified"]

:::warning Note on Webhooks

• EMAIL_CHANGED is triggered only for email modifications.
• Mobile number changes do not trigger webhook events at this time. :::

---

Change Email/Mobile During Login or Registration (trackId Flow)

If a user realizes they made a typo during registration or needs to update their contact details during an active login flow, they can do so using a trackId.

• Endpoint: POST /useractions-srv/communication/medium/track/{trackId}?action={initiate|validate}
• API Reference: POST /useractions-srv/communication/medium/track/:trackId
• Guide: Communication Change During Verification

Key Differences from Profile Change:

1. No Token Required: Uses trackId instead of an active user Access Token, allowing changes before the user completes login.
2. Context Preservation: Automatically cancels pending verifications for the old value and starts a new verification for the new value, keeping the session active.

---

Tutorial Video

Learn how to change the email or mobile number with our academic tutorial video:

:::tip Need Support? Please contact us directly on our support page. :::