Communication Change
Overview
Communication medium verification is a token condition assessed prior to issuing a token. It lets applications mandate verification of one or both communication channels — email and mobile number — based on client requirements, ensuring the necessary 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. It 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 notice an error.
Automatic flow management: When contact information is changed:
- The system immediately cancels any ongoing verification (OTP or email link) tied to the old contact details.
- 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
communication_verification step, receives an OTP, then decides to use a different email/mobile because of a typo. The system cancels the first attempt and starts 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 services that require a higher validity of the user's account. It is a one-time verification that occurs only if the user has not previously confirmed their communication mediums, adding an extra layer of authentication.
Configure communication medium verification
You configure this per application in User Setup → Communication Medium Verification (the dropdown shown below). Each option maps to a login-time behavior:
Option (communication_medium_verification) | Behavior |
|---|---|
None (none) | No verification is required for the user to use this application. |
Mobile and email verification required (mobile_and_email_verification_required) | Both email and mobile number must be verified when logging in to the application. |
Verification required on usage (verification_required_on_usage) | Verification is required based on the identifier used — e.g. logging in with an unverified email prompts email verification, while logging in with an already-verified mobile number proceeds automatically. |
Email verification required (email_verification_required) | Email verification is always required, independent of the identifier used to log in. |
Mobile verification required (mobile_verification_required) | Mobile verification is always required, independent of the identifier used to log in. |
Email verification required on usage (email_verification_required_on_usage) | Email verification is required only when logging in with email; logging in with mobile is unaffected by the email verified state. |
Mobile verification required on usage (mobile_verification_required_on_usage) | Mobile verification is required only when logging in with mobile; logging in with email is unaffected by the mobile verified state. |
Understanding the flow and APIs
Step 1: Initiate the communication change
When a user needs to change their communication medium during verification, they can initiate this change through a dedicated API. This API updates the status of the user's communication medium — email or mobile number — by switching it between verified and unverified states, so 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 the 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 confirms the updated contact information is accurate and verified, allowing the user to continue securely and complete token issuance based on the newly verified medium.
| API | Description | Link |
|---|---|---|
| POST Communication Change Validation | To validate the new communication medium with the 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 triggers 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
};
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
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
Please contact us on our Developer Support Page