Adding an email credential

email: null is what routes you to this scenario rather than to a change (scenario 30). hasPassword is the other field to read: A PASSWORD IS REQUIRED AND THERE IS NO IN-APP WAY TO SET A FIRST ONE — both the step-up and the request answer 409 no_password. A phone-first account created by the DEPRECATED one-shot sign-up has none, and gets one through the reset flow on its verified phone (scenario 34) before coming back here.

Proves the CURRENT password and answers { challengeId, stepUpToken, assurance: password, expiresIn, passwordOnlyAllowed, options[], loginChannel? } — both ids are captured and filled into the cards below. 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 is 401 step_up_required. passwordOnlyAllowed says whether this password token already suffices; when false, prove one of options[] (a code to a verified, non-young CURRENT value — never a pending one — a TOTP, or a recovery code) for a strong token. Errors: wrong password 401 step_up_failed (counted per user AND per session — 5 in 15 min → 429, and 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 this action (details[0].blocking). The factors on offer are the verified PHONE (the other channel), a TOTP or a recovery code — there is no current-value factor, because the email is the thing being added. A PHONE THAT IS ITSELF RECENT CANNOT VOUCH FOR THE EMAIL: a channel whose current value was applied with password-only assurance inside CHANNEL_TRUST_AGE_SECONDS (default 30 days) is “young” and is not offered, because a channel a password alone could have set must not then authorise the next change. For an ordinary phone-first account this does NOT bite — a phone verified during registration carries no such record — but an account that added or replaced its phone on a password-only token in the last 30 days, with no TOTP and no recovery codes, has no eligible factor at all and its first email is held the full three days.

Only for a CODE factor: factor is email_code or phone_code and must be one of the challenge's options[] (else 422 factor_not_eligible). 202 { status, masked, ttlSeconds }. The code is BOUND to this challenge, and a second send retires the first. Skip this card for a TOTP or a recovery code — they go straight to verify. 404 for an unknown or expired challenge (STEP_UP_CHALLENGE_TTL_SECONDS, default 600); 429 on the per-user, per-channel send throttle.

factor is email_code · phone_code · totp · recovery_code (one of the challenge's options), code is the value that proves it. 200 { stepUpToken, assurance: strong, expiresIn } — captured, and it REPLACES the password token in the card that spends it. The password token stays valid alongside it. A used recovery code is consumed. Wrong, expired or exhausted code → 401 step_up_failed; the challenge takes STEP_UP_MAX_ATTEMPTS (default 5) wrong codes and closes once it succeeds or is exhausted.

email is trimmed, ≤ 320 chars, NFC-normalized; stepUpToken is an email_change token — password or strong. 202 with the CredentialChange row (id, kind, value, status awaiting_verification, assurance, requestedAt / verifiedAt / effectiveAt / expiresAt / codeExpiresAt, codeSentTo). The code is the contact_change.email message (15 min). A PASSWORD-assurance request also sends contact_change_requested to every verified current channel, carrying a single-use cancel link; a strong one sends nothing at request. Unverified, the change expires after CONTACT_CHANGE_PENDING_TTL_SECONDS (default 24 h). 409 conflict when the address belongs to another live account (re-checked at verify, and again by J7 during a hold) or an Idempotency-Key is reused with another body; 409 change_in_progress (one live change per kind; email beside phone only when BOTH are strong; never beside a password change); 409 no_password; 429 over CREDENTIAL_CHANGE_MAX_PER_DAY (default 5). 422 unchanged CANNOT fire here: it means “already your verified current address”, which an account with no address does not have. The request notice goes to the verified PHONE, since there is no old address to tell, and carries the sessionless cancel link (scenario 36).

202 { ttlSeconds } — a fresh code to the new address; the previous code dies. 409 no_pending_change; 429 at 5 per 15 min per change and per destination.

204, idempotent, NO step-up — cancelling only ever keeps the current value. Works while awaiting the code or held. Every verified current channel receives contact_change_cancelled and the cancel link is burnt. Every live change at once is DELETE /v1/me/credential-changes (scenario 36).

The code sent to the NEW address (4–8 digits). STRONG → applied now: email becomes the new address, verified; user.upserted is projected once per app across your tenants. PASSWORD → HELD for CONTACT_CHANGE_HOLD_SECONDS (default 3 days): every verified current channel receives contact_change_held naming the effective time and carrying the SAME cancel link, and worker job J7 applies it at effectiveAt. 200 with the row, status applied or held. 401 invalid_code (the 5th wrong code burns it — resend restores); 409 no_pending_change; 409 conflict when the address was taken meanwhile (the change is failed and contact_change_failed is sent). If the address was a typo this step never happens and the change expires after 24 h. Never mints a session or device trust. NO SEPARATE VERIFICATION STEP: the code sent to the new address IS the verification, so on apply email and emailVerifiedAt are set together — POST /v1/auth/email/verify is registration-only and plays no part here. IT DOES NOT CHANGE HOW YOU SIGN IN: loginMode stays phone until it is changed deliberately (scenario 33), and the new address unlocks email_code as a step-up and new-device factor only once it is verified and no longer young.