Changing your email address

STEP-UP REQUIRED — the body carries currentPassword OR otpCode ({ ≥ 1 }), exactly as the loginMode change does (scenario 31). A live session alone is NOT sufficient, and a supplied-but-wrong currentPassword is refused rather than ignored (AUTH-IAM-01): since the email is the address password recovery is sent to, an attacker holding a stolen session who could point recovery at an address they control would turn a temporary session theft into permanent ownership of the account. ⚠ DOC DISCREPANCY — §2.28 states this step-up plainly, but §3.20's field table marks currentPassword “required (with otpCode as the alternative) ONLY when loginMode changes” and lists no 401 among its errors. If a bare { email } is accepted with 200 here, the service implements the §3.20 reading and §2.28 is aspirational; the factor is a settable field either way, so sending it can never be the reason a call fails. Report which one the service actually does. The change is STAGED, not applied: the new address goes to pending_email and a single-use verify token (24h) + short code are issued to it out-of-band. The 200 reflects the CURRENT (unchanged) email and emailVerifiedAt, and echoes the staged address as pendingEmail so the UI can name where the link went. 409 conflict if the new email already belongs to another active identity (checked at stage time; a race that claims it before confirmation surfaces as 409 at verify). THE ACCOUNT IS NEVER LOCKED OUT BY AN EMAIL CHANGE — login keeps working on the current verified email until the new one is confirmed; only after confirmation does login require the new address. If the address was a typo, step 2 never happens and the account keeps working on its old email. NO PROJECTION EVENT IS EMITTED: displayName is a projected column (app.users.display_name) and this handler contains no outbox write at all, so a user renaming themselves reaches no app at the request — the reconciler picks it up within PROJECTION_RECONCILE_INTERVAL_MS (default 1h) because the update bumps row_version and the ledger row already exists. An app's copy of a display name is therefore UP TO AN HOUR STALE BY DESIGN, which is a stale row rather than a missing one and needs no repair (scenario 42). The email path is unaffected in practice — the change is staged, and the verify step that activates it does emit user.upserted.

Re-read the profile at any time while a change is staged: pendingEmail is non-null until the verify completes, which is how a UI shows a “waiting on ada+new@acme.io — resend?” banner across page loads. The internal columns (password hash, the staged address's token) are never returned.

Submit EITHER { token } (the 24h link) OR { email, code } (the 6-digit code, 15 min) — they are two halves of ONE challenge row, so redeeming either kills the other, and exhausting the code's attempt cap (EMAIL_CODE_MAX_ATTEMPTS, default 5) consumes the row and takes the link with it. On an account that already has an active membership the 200 carries an accessToken + refresh cookie (amr: [email]) — verification now ends in a session; an invitee with no active membership still gets {}.

202 for an address still awaiting confirmation (a not-yet-verified active email OR a staged pending_email); 409 when there is nothing to send (unknown email OR already verified) — an OR-list message that never discloses which. Always re-mints BOTH halves together, so the newest message is internally consistent.