Communication Change

Overview

Communication medium verification is a token condition assessed prior to issuing a token. It allows applications to mandate verification of one or both communication channels—email and mobile number—based on client requirements. This feature ensures that the necessary communication mediums are verified to meet security policies before granting access via the token

Introduction to communication medium verification

What is communication medium change?

Communication medium verification is a token condition evaluated before token issuance. This process verifies email addresses and mobile numbers while allowing users to correct contact information during verification.

How It Works

Verification Flexibility: Users can update their email address or mobile number during registration or login if they identify an error.

Automatic Flow Management: When contact information is changed:

1. The system immediately cancels any ongoing verification (OTP or email link) tied to the old contact details.
2. A new verification attempt is automatically triggered using the updated information.

Purpose: Ensures accurate contact information while maintaining security through proper verification of the correct communication medium.

Example Scenarios

Registration Phase:

• A user signs up and accidentally enters a wrong email or mobile number
• Before completing the verification, they realize and want to correct it
• The system must allow the user to change the email/number and resend the verification code

Verification Step:

• User enters email/mobile → logs in and reaches communication_verification step → receives OTP → decides to use a different email/mobile, because of typo
• System must cancel the first attempt and start a new verification flow for the updated medium

When is a user asked for communication medium verification?

Communication medium verification is typically requested during account creation or when a user starts using more sensitive or sophisticated services of yours, which require a higher validity of the user's account. It's a one-time verification that occurs only if the user has not previously confirmed their communication mediums, adding an extra layer of authentication to the user's account.

When a user changes their email address or mobile number you can directly apply a verification during the change process. More information you can find in the email and mobile change documentation

Criteria	Example	Configuration
not verified email or mobile number	The user has not verified his email or mobile number, as required by the application. Please find below all respective options
communication_medium_verification as none	No verifications are required for user to use this application
communication_medium_verification as mobile_and_email_verification_required	Both email and mobile_number verification required while login to the application
communication_medium_verification as verification_required_on_usage	verification required based on the identifier used by user e.g.: if a user tries to login with email but email is not verified then, the user will be prompted to verify the email, whereas when he uses mobile_number which is verified, the user will be automatically logged in.
communication_medium_verification as email_verification_required	always email verification is required independent of the identifier used to login the application
communication_medium_verification as mobile_verification_required	always mobile verification is required independent of the identifier used to login the application
communication_medium_verification as email_verification_required_on_usage	email verification is only required when identifier email is used to login, if mobile number is used, the user will be able to login independent of the mobile_number_verified state
communication_medium_verification as mobile_verification_required_on_usage	mobile verification is only required when identifier mobile is used to login, if email is used, the user will be able to login independent of the email_verified state

Understanding the Flow and APIs

Step 1: Initiate the communication change

When a user needs to change their communication medium during the verification process, they can initiate this change through a dedicated API. This API allows updating the status of the user's communication medium—whether email or mobile number—by switching it between verified and unverified states. This functionality ensures users can seamlessly update their contact information to continue with verification and token issuance without interruption.

API	Description	Link
POST Communication Change Initiation	To initiate the communication medium change during verification flow	View API

Step 2: Validate the communication change

After receiving the verification code on the new communication medium, the user validates the change by entering the code. This confirmation step ensures that the updated contact information is accurate and verified, allowing the user to continue with the verification process securely and complete the token issuance based on the newly verified communication medium.

API	Description	Link
POST Communication Change Validation	To validate the new communication medium with verification code	View API

This enhanced process ensures both user convenience and system security while maintaining the integrity of the verification flow.

Implementation using Typescript

This Implementation Guide is based on the default hosted pages which use an Angular framework based on TypeScript. It can be implemented in any other programming language as well.

Step 1: Init the communication change

When a user needs to change their communication medium during verification:

const initiateCommunicationChange = async (trackId: string, newMedium: string, newValue: string) => {
    try {
        const payload = {
            medium: newMedium, // "email" or "mobile_number"
            value: newValue, // new email or mobile number
            processingType: "CODE", // or "LINK"
            reason: "User corrected communication medium"
        };

        const response = await fetch(`${baseUrl}/useractions-srv/communication/medium/track/${trackId}?action=initiate`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${accessToken}`
            },
            body: JSON.stringify(payload)
        });

        if (response.ok) {
            const result = await response.json();
            console.log('Communication change initiated:', result);
            return result;
        } else {
            throw new Error(`Failed to initiate communication change: ${response.statusText}`);
        }
    } catch (error) {
        console.error('Error initiating communication change:', error);
        throw error;
    }
};

This will trigger a new verification code to be sent to the updated communication medium.

Step 2: Verify the communication change

To finally proceed to verify the initiated communication change:

const validateCommunicationChange = async (trackId: string, verificationCode: string) => {
    try {
        const payload = {
            code: verificationCode, // verification code received on new medium
            medium: "email", // or "mobile_number" - the medium being verified
            value: "[email protected]" // the new value being verified
        };

        const response = await fetch(`${baseUrl}/useractions-srv/communication/medium/track/${trackId}?action=validate`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'Authorization': `Bearer ${accessToken}`
            },
            body: JSON.stringify(payload)
        });

        if (response.ok) {
            const result = await response.json();
            console.log('Communication change validated:', result);
            // User will be redirected to continue the authentication flow
            return result;
        } else {
            const error = await response.json();
            throw new Error(`Validation failed: ${error.error_description}`);
        }
    } catch (error) {
        console.error('Error validating communication change:', error);
        throw error;
    }
};

Complete Example Usage

// Example: User realizes they entered wrong email during verification
const handleCommunicationChange = async () => {
    const trackId = getTrackIdFromUrl(); // Extract from current verification URL
    const newEmail = "[email protected]";
    
    try {
        // Step 1: Initiate the change
        await initiateCommunicationChange(trackId, "email", newEmail);
        
        // Step 2: User receives code and enters it
        const userEnteredCode = await promptUserForCode();
        
        // Step 3: Validate the change
        await validateCommunicationChange(trackId, userEnteredCode);
        
        console.log('Communication medium successfully updated!');
    } catch (error) {
        console.error('Failed to change communication medium:', error);
    }
};

Explore Related Topics

• Claim Consent Precheck
• Login Success
• Scope Consent

---

Need help implementing this?

Please contact us on our Developer Support Page