Change Email Phone Number Applet

Overview

This applet is four self-service pages, not a console: change e-mail, change mobile number, add e-mail (for a login that only has a mobile number) and add mobile number (for a login that only has an e-mail). Each one walks the user through a verification code sent to the identity they already hold, then a second code sent to the new identity, and only then changes the login principal. It has no menu, no listing and no settings — the CoreComponent is a bare <router-outlet>.

It is registered as ROOT-ADMIN, but it is not an administrator’s tool: the backend accepts the request from the user whose login is being changed, or from someone holding a tenant-owner / admin or user-profile-owner / admin permission. Measured 2026-09-16, it is in no catalogue and installed for nobody — users reach it by URL, typically by redirect from the profile screen or from a mobile app, with the parameters described under Configuration.

Where it fits

Direction	What	Why
Upstream	The user-profile screen (`/#/akaun-user-profile-applet/my-profile`) and mobile apps	Send the user here; the applet links back to my-profile when done.
Sibling	Platform SysAdmin → User	A system administrator sees the login’s principals there but cannot change them; the backend’s `…/sysadmin-ep` variants of these endpoints exist and are not called by any screen.
Sibling	Tenant Admin Applet	Tenant-side user administration.

Screens and menus

Routes under akaun-change-email-mobile-number-applet (the registry routerLink matches):

Route	Screen	Steps
`change-email` (default)	Change Email	1. Enter Current Email, Request code, enter Verification Code. 2. Enter New Email, Request code, enter the code. Then Back / link to my-profile.
`change-mobile-number`	Change Mobile Number	Same two steps with a country-code picker (`GET …/countries`) and mobile numbers.
`add-email`	Add Email	One step: Current Mobile Number (read-only, verified) → New Email → code.
`add-mobile-number`	Add Mobile Number	One step, mirror of Add Email.

Configuration

Before you can use it

Authentication, one of two ways (change-email.component.ts L80–L105). Either the browser holds a login token (localStorage.authToken), or the URL carries accessId and accessKey query parameters, in which case the applet calls the -access-key twins of every endpoint. With neither, the page redirects to /#/auth/login.
Whose login is changed is subjectGuid from the URL if present, else the signed-in user’s own guid. The backend accepts the change when the token’s subject is that guid, or when the caller holds MST_TENANT_OWNER, MST_TENANT_ADMIN, MST_LOG_USER_PROFILE_OWNER or MST_LOG_USER_PROFILE_ADMIN (IdentityUserProfileController.java L352–L400 and the parallel blocks for mobile number, add-email and add-mobile-number).
Optional URL parameters tenantCode + websiteCode make the page load that website’s branding (GET …/websites public criteria); without them the hostname’s branding is used. messageTemplate, isApp and state are passed through to the verification request.

Applet settings

No exposed control found (routes checked at commit 061764f): the applet has no settings route, no personalization route, and reads no applet setting.

Settings in other applets that control this applet

None found.

Feature visibility / permissions

bl_applet_client_side_perm_dfn has 0 rows for this applet (queried 2026-09-16); nothing is gated client-side.

Fields

Change Email / Change Mobile Number

Field	Meaning	Required	Notes
Current Email / Current Mobile Number	The principal the login already has	Yes	Validated against `EmailMobileNumberPatternValidation` before Request code is enabled.
Verification Code (step 1)	Code sent to the current identity	Yes	With the `key` returned by the request call.
New Email / New Mobile Number	The principal to switch to	Yes
Verification Code (step 2)	Code sent to the new identity	Yes

Add Email / Add Mobile Number

The current identity of the other type (read-only once verified), the new identity, and one verification code.

Lifecycle and effects

All calls go to POST /core2/platform/dm/identity/userprofile/… (ts-lib UserProfileService, endpoint_path at L22), each with an -access-key twin chosen when the URL carried an access key.

Step	Endpoint	Effect
Request code to current identity	`request-existing-identity-verification-for-change-email` / `…-for-change-mobile-number`	Sends a code; returns a `key`.
Verify current identity	`existing-identity-verification-for-change-email-mobile-number`	Marks the existing principal verified for this change.
Request code to new identity	`change-email` / `change-mobile-number` / `add-email` / `add-mobile-number`	Sends a code to the new address or number; rejects an address or number already used by another login (`EMAIL_ALREADY_EXISTS`, `MOBILE_NUMBER_ALREADY_EXISTS`).
Verify new identity	`new-identity-verification-for-change-email-mobile-number`	Applies the change to `app_login_principal`.

No stock or journal effect.

Related applets

Platform SysAdmin — where an administrator sees a login’s principals (User → Edit).
Tenant Admin Applet — tenant-side user administration.

Troubleshooting

The applet maps backend response codes to messages in error-handler.service.ts (L11–L40):

Code	Meaning	What to do
`CLIENT_AUTH_USER_NOT_AUTHORIZED`	Token subject is not the login being changed and holds none of the four permissions.	Sign in as that user, or pass `subjectGuid` only when you hold the permission.
`CLIENT_VALIDATION_NO_EMAIL` / `NO_MOBILE_NUMBER` / `INVALID_EMAIL` / `INVALID_MOBILE_NUMBER`	Empty or malformed identity.	Correct the value.
`CLIENT_CHANGE_EMAIL_MOBILE_NUMBER_NO_KEY` / `CLIENT_VALIDATION_NO_CODE`	Verify was called before request, or the code field is empty.	Request the code first.
`CLIENT_CHANGE_EMAIL_MOBILE_NUMBER_NOT_VERIFIED`	Step 2 attempted before step 1 succeeded.	Verify the current identity first.
`CLIENT_CHANGE_EMAIL_MOBILE_NUMBER_NEW_PRINCIPAL_ID_ALREADY_VERIFIED`	The new identity was already verified for this change.	Continue to the final step.
`VERIFICATION_FAILED`	Wrong or expired code.	Request a new code.
`EMAIL_ALREADY_EXISTS` / `MOBILE_NUMBER_ALREADY_EXISTS`	Another login already uses it.	Use a different identity.
`ALREADY_HAS_EMAIL_APP_LOGIN_PRINCIPAL` / `ALREADY_HAS_MOBILE_APP_LOGIN_PRINCIPAL`	Add used on a login that already has that type.	Use Change instead.
Page bounces to the login screen	Neither a token nor `accessId` + `accessKey` was present.	Open it from the profile screen while signed in, or with the access-key parameters.