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 focus

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	When providing action initiate the change will be intiated and the Template VERIFY_USER will be triggered for the new value	Link to API
Change or update email or mobile number	When providing action validate the change will be confirmed and after successfully entering the correct OTP the Template NOTIFY_COMMUNICATION_CHANGE will be triggered for the old value	Link to API

Step 1: Load User Data

First, you need to provide an option in the User-Profile so the user is able to change their email or mobile number

API	Description	Link
GET User Info	Allows to retrieve user information for their own profile	Link to API

The initiation payload requires provider, sub, last_used_identity_id in the next Step 2..

Step 2: Show the Update Button when Field Changed & Trigger the Communication Medium Change

After they change the mobile or email you can show a button to continue. This button triggers the below API using a user Token as Authorization Header, as well as providing action as initiate.

API	Description	Link
Change or update email or mobile number	When providing action initiate he change will be initiated.	Link to API

let payload: ICommunicationMediumVerification = {
        medium: this.data.fieldKey,
        value: value, //this is the new value for mobile number or email address
        sub: this.userInfo.sub,
        provider: this.userInfo.provider
}

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

Email Template: The initiation of an email or mobile change implicitly triggers an OTP email/SMS. The template VERIFY_USER will be used for formatting the OTP message sent to the new email address or mobile number.

Step 3: Handling Communication Medium Change

Now the UI should open a popup or a new window, to allow the user to enter the OTP which was just sent. Be careful to also handle the error messages e.g. if a user already exists with this identifier. Depending on the response you can present the error and close the tab.

Step 4: Verify the OTP for Communication Medium Change

The last step is that the user received the OTP and now wants to enter it. Therefore, a text field and a button are sufficient, which allows to trigger the validation with action validate.

let payload: ICommunicationMediumVerification = {
        code: value.code, //this is the code to be entered by the user
        medium: this.data.fieldKey,
        value: value, //this is the new value for mobile number or email address
        sub: this.userInfo.sub,
        provider: this.userInfo.provider
}

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

API	Description	Link
Change or update email or mobile number	When providing action validate, the change will be confirmed and the value will be updated in the user's profile	Link to API

Notification Template: After successful validation, the template NOTIFY_COMMUNICATION_CHANGE will be sent to the old email address or mobile number to notify the user about the change. This notification can be disabled in tenant configuration.

Webhook: An EMAIL_CHANGED fact event is automatically created and sent as a webhook after successful email change.

Email Templates

There are two templates that are triggered during the communication medium change process:

Template Key	Description	When Sent	Recipient	Variables
VERIFY_USER	Sends OTP verification code to the new email address or mobile number	During initiate action	New email/mobile	{{code}}, {{name}}, {{account_name}}
NOTIFY_COMMUNICATION_CHANGE	Notifies the old email/mobile about 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 the new communication medium (email or mobile number)
• Trigger: When action=initiate is called
• Recipient: The new email address or mobile number provided in the request
• Processing Type: CODE (OTP)
• Locale: Based on Accept-Language header or tenant default

NOTIFY_COMMUNICATION_CHANGE Template:

• Purpose: Inform the user about the communication medium change on their old contact method
• Trigger: After successful action=validate completes
• Recipient: The old email address or mobile number (before the change)
• Processing Type: EMAIL or SMS
• Locale: Based on Accept-Language header or tenant default
• Note: Only sent if the old communication medium exists and is not empty

Webhooks and Facts

When a communication medium (email) is successfully changed, a fact event is automatically created and sent as a webhook:

Event Type	Object Type	Object ID	Description	Webhook Attributes
EMAIL_CHANGED	users	sub (user ID)	Email address was changed	For instant change: ["identity_id", "sub"] For verified change: ["email", "email_verified"]

Webhook Details

Event Type: EMAIL_CHANGED

When Triggered:

• After successful email change (both instant and verified changes)
• Only for email changes (not mobile number changes)

Webhook Payload:

• Object Type: users
• Object ID: User's sub (subject identifier)
• New Value: Contains the new email address
• Old Value: Contains the previous email address
• Webhook Attributes: Varies based on change type (instant vs verified)

Webhook URL: {public_url}/users-webapp/{objectType}/{objectId}

Note: Mobile number changes do not currently trigger webhook events.

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

Users can change their email or mobile number during the login or registration verification process using a trackId. This is useful when users realize they entered incorrect contact information during registration or when verification is required during login.

Related Documentation: Communication Change During Verification

API Endpoint:

POST /useractions-srv/communication/medium/track/{trackId}?action={initiate|validate}

API Reference: POST /useractions-srv/communication/medium/track/:trackId

This flow allows users to:

• Correct typos in email/mobile during verification
• Update contact information before completing verification
• Seamlessly continue the authentication flow after correction

Key Differences from Profile Change:

• Uses trackId instead of user token (no authentication token required)
• Works during active authentication/verification flow
• Automatically cancels old verification and starts new one
• No separate profile update required
• Uses same templates (VERIFY_USER for OTP, NOTIFY_COMMUNICATION_CHANGE for notification)

When to Use:

• Profile Change Flow (PUT /useractions-srv/communication/medium/{sub}): When user is already logged in and wants to update their profile
• trackId Flow (POST /useractions-srv/communication/medium/track/{trackId}): When user is in the middle of registration/login verification and needs to correct contact information

Learn how to change the email or mobile number, with our exclusive academic tutorial.

Need Support?

Please contact us directly on our support page