Changing your email address

Starts a step-up (E-1) for ONE named profile action: proves the CURRENT password and answers 200 { challengeId, stepUpToken, assurance: password, expiresIn, passwordOnlyAllowed, options[], loginChannel? }. Every profile mutation — display name, login mode, email / phone / password change, phone removal, MFA disable, recovery-code regeneration — spends one of these tokens; a live session alone is never enough. Auth + throttled + no-store; the body is .strict(). THE TESTER AUTO-CAPTURES BOTH IDS: challengeId is filled into the …/code and …/verify cards on this page, and stepUpToken into the card that spends it. The token is single-use and bound to this user, this SESSION, this action and the assurance it reached (STEP_UP_TOKEN_TTL_SECONDS, default 300); spending it on another action, from another session, or twice → 401 step_up_required. passwordOnlyAllowed says whether this password token already suffices for the action; when false, continue with …/code (for a code factor) and …/verify for a strong token. options[] are the factors …/verify will accept: a code factor always names the CURRENT value on the account — never a pending one — and only when it is verified and not young (applied with password assurance inside CHANNEL_TRUST_AGE_SECONDS, default 30 days); totp appears when a confirmed authenticator exists, recovery_code while unused codes remain. The challenge lives STEP_UP_CHALLENGE_TTL_SECONDS (default 600) and takes STEP_UP_MAX_ATTEMPTS (default 5) wrong codes. Errors: 401 step_up_failed (wrong password — counted per user AND per session, 5 in 15 min → 429, a second throttle trip within 24 h revokes the session) · 403 without an acting session (operator / act-as contexts have none) · 409 no_password (GET /v1/me → hasPassword: false; set one through the reset flow, scenario 34) · 409 change_in_progress when a live change blocks the action (details[0].blocking lists { kind, status }) · 409 login_channel_unavailable (password_change with no verified loginMode channel). Audited step_up_succeeded / step_up_failed.

Sends a step-up code (E-2) to ONE of the challenge's channel options — the step_up.<action> message, in the caller's locale. 202 { status: accepted, masked, ttlSeconds }. The code is bound to THIS challenge, and a second send retires the first. Each code sent takes STEP_UP_MAX_ATTEMPTS (default 5) wrong guesses — email and phone alike — after which that CODE is burnt and a resend is needed; the challenge itself is separately capped at 5 failed proofs of any factor code. Auth + throttled (per user, per channel → 429) + no-store; the body is .strict(). Only needed for a code factor — a totp or recovery_code factor goes straight to …/verify. 404 when there is no such (live) challenge for the caller; 422 factor_not_eligible when the factor is not among the challenge's options.

Proves a factor (E-3) — the code from …/code, a TOTP, or a recovery code — and answers 200 { stepUpToken, assurance: strong, expiresIn } for the SAME action. THE TESTER CAPTURES IT and it REPLACES the password token in the card that spends it; the password token from the start stays valid alongside it. The challenge closes once it succeeds or its attempts are exhausted (STEP_UP_MAX_ATTEMPTS, default 5). Auth + no-store; .strict(). Errors: 401 step_up_failed (wrong, expired or exhausted code; a TOTP or recovery code that did not verify; and the CHALLENGE as a whole takes STEP_UP_MAX_ATTEMPTS (default 5) failed proofs of ANY factor, after which it is DELETED and every later call answers 404) · 404 no such challenge · 422 factor_not_eligible. A used recovery code is consumed. Audited step_up_succeeded with stepUpMethod = the factor.

Requests an email change (E-5). 202 with the CredentialChange row { id, kind: email, value, status: awaiting_verification, assurance, requestedAt, expiresAt, codeExpiresAt, codeSentTo, … }. A code (contact_change.email, 15 min) goes to the NEW address; until the change applies the CURRENT address keeps signing in and a pending value never does — read it back as pendingEmail / pendingChanges at GET /v1/me. Auth + throttled + no-store; .strict(). ASSURANCE DECIDES WHAT FOLLOWS: a PASSWORD-assurance request also sends contact_change_requested to every verified current channel carrying a single-use sessionless CANCEL LINK (scenario 36), and its verify is HELD for 3 days; a STRONG request sends nothing now and applies at verify. An add over a never-verified current email burns that address's registration-era verify tokens. Expires unverified after CONTACT_CHANGE_PENDING_TTL_SECONDS (default 24 h). Errors: 401 step_up_required · 409 no_password · 409 change_in_progress (one live change per kind; email beside phone only when BOTH are strong; never beside a password change) · 409 conflict (the address belongs to another account, or an Idempotency-Key reused with another body) · 422 unchanged (already your verified address) · 429 over CREDENTIAL_CHANGE_MAX_PER_DAY (default 5 in 24 h). Walk-through: scenario 30.

Confirms the code sent to the NEW address (E-6). 200 with the CredentialChange row. What happens next depends on the assurance the request spent: STRONG → status applied — email becomes the new address, verified; user.upserted is projected once per app across the user's tenants; the OLD address and the other verified channel receive contact_change_applied. PASSWORD → status held for CONTACT_CHANGE_HOLD_SECONDS (default 3 days) — the current address keeps signing in, every verified current channel receives contact_change_held naming effectiveAt and carrying the SAME cancel link as the request notice, and worker job J7 applies it at effectiveAt. Never mints a session and never grants device trust. Auth + no-store; .strict(). This — not POST /v1/auth/email/verify — is where an email change is confirmed. Errors: 401 invalid_code (wrong, expired or used; the 5th wrong code burns it — resend restores) · 409 no_pending_change · 409 conflict (the address was taken meanwhile — the change is failed and contact_change_failed is sent).