Change Email/Mobile via Backend

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 user with the 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 his account information, also a email and mobile number can be updated. Thereby the values are instantly applied to his 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.

Let us see the process.

Enforce Verification before Communication Medium Change

The below section will focus on how to enforce a verification using Links before changing the communication medium.

Administrative Communication Medium Change via Link

The administrative communication medium change allows administrators to initiate email or mobile number changes on behalf of users through a secure link-based verification process.

How does admin-initiated communication medium change work?

1. Administrator initiates the change using the administrative API with elevated permissions
2. System validates the request and checks for conflicts with existing users
3. Verification link is generated and sent to the new email/mobile address
4. User receives notification with a secure link that expires in 7 days
5. User clicks the link to confirm the communication medium change
6. System updates the user's profile with the new contact information
7. System notifies the old email/mobile about the change

Email Templates

There are two templates used in the administrative communication medium change process:

Template Key	Description	When Sent	Recipient	Variables
VERIFY_COMMUNICATION_CHANGE	Sends verification link to the new email address or mobile number	When admin initiates change	New email/mobile	{{verify_link}}, {{name}}, {{account_name}}, {{cancellation_link}}
NOTIFY_COMMUNICATION_CHANGE	Notifies the old email/mobile about the change	After user confirms change via link	Old email/mobile	{{communication_medium_value}}, {{name}}, {{account_name}}, {{communication_medium_name}}

Template Details

VERIFY_COMMUNICATION_CHANGE Template:

• Purpose: Send verification link to the new communication medium
• Trigger: When admin initiates change via POST /useractions-srv/communication/medium/{sub}
• Recipient: The new email address or mobile number
• Processing Type: LINK (verification link with 7-day expiration)
• 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 user clicks verification link and confirms the change
• 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

Webhooks and Facts

When a communication medium (email) is successfully changed via administrative flow, 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 by admin	["email", "email_verified"]

Webhook Details

Event Type: EMAIL_CHANGED

When Triggered:

• After user confirms the change by clicking the verification link
• 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: ["email", "email_verified"]

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

Technical Integration: Administrative Communication Medium Change

The administrative change process uses a different API endpoint and requires elevated permissions.

API	Description	Link
Administrative Communication Medium Change	Allows administrators to initiate communication medium changes via link-based verification	Link to API

Step 1: Administrative Request Initiation

Administrators with proper permissions can initiate a communication medium change using the following API:

// Define proper interface for the payload
interface CommunicationMediumChangePayload {
    sub: string;
    provider: string;
    medium: 'email' | 'mobile';
    value: string;
    initiate_login_uri: string;
}

// Define response interface
interface CommunicationMediumChangeResponse {
    success: boolean;
    data: any;
}

// Step 1: Administrative Request Initiation
async function initiateCommunicationMediumChange(
    userSub: string, 
    adminToken: string
): Promise<CommunicationMediumChangeResponse> {
    
    const payload: CommunicationMediumChangePayload = {
        sub: "6755f31b-677d-4f98-9cd7-d722c2071a22",
        provider: "self",
        medium: "email",
        value: "[email protected]",
        initiate_login_uri: "https://mypage.de/login"
    };

    try {
        // Requires admin token with 'cidaas:users_write' scope and CIDAAS_ADMINS group membership
        const response = await fetch(`${this.baseUrl}/useractions-srv/communication/medium/${userSub}`, {
            method: 'POST',
            headers: {
                'Authorization': `Bearer ${adminToken}`,
                'Content-Type': 'application/json',
                'Accept': 'application/json'
            },
            body: JSON.stringify(payload)
        });

        if (!response.ok) {
            throw new Error(`HTTP error! status: ${response.status}`);
        }

        return await response.json() as CommunicationMediumChangeResponse;
        
    } catch (error) {
        console.error('Failed to initiate communication medium change:', error);
        throw error;
    }
}

Need Support?

Please contact us directly on our support page