Adding a phone credential

Profile & credentials

A signed-in user who has NO phone links one, so it can carry a sign-in code, a second factor, or become the primary channel. Routed here by phone: null on GET /v1/me. Replacing a number you already hold is the same route with different consequences (scenario 32). Not policy-gated.

GET /v1/me → phone: null is what routes you here; hasPassword says whether the step-up can even start
POST /v1/me/step-up { action: phone_change, currentPassword } → a step-up token (+ …/code and …/verify for a STRONG one)
POST /v1/me/phone-change { phone, stepUpToken } → 202; a WhatsApp/SMS code (5 min) goes to the new number
Optional: POST /v1/me/phone-change/resend → a fresh code, the previous one dies · DELETE /v1/me/phone-change → 204 to cancel, idempotent, no step-up
POST /v1/me/phone-change/verify { code } → strong: phone + phoneVerifiedAt are set now · password: held three days, then applied by worker job J7

GET/v1/meauthDo I have a phone yet? (phone: null routes you here)

phone: null is what routes you to this scenario rather than to a replacement (scenario 32). A PASSWORD IS REQUIRED: both the step-up and the request answer 409 no_password without one — every credential change is gated on proving the current password, so an account that has never had one sets it through the reset flow first (scenario 34).

ℹ︎Field guide — what each value means & where it comes fromno inputs

No request body, path params, query params, or caller-set headers. It only needs the authenticated session: the tester sends the captured Authorization access token and the gateway injects x-gateway-context. Returns the current user's profile — id, email, phone, displayName, hasMfaEnabled, emailVerifiedAt, phoneVerifiedAt, loginMode — plus the fields the §153 / §136 flows read first: hasPassword (false → every profile change is refused 409 no_password at POST /v1/me/step-up; set one through the reset flow, scenario 34), pendingEmail / pendingPhone and pendingChanges[] (the live credential changes in CredentialChange shape — email and phone keep naming the values that still sign in, scenario 36), and foundedTenantId (null → founding is offered; set → POST /v1/me/organizations would only 409, scenario 24). 404 if the user record is gone.

Bearer token

Send Authorization: Bearer (no token set!)

→ GET https://api.kerja.team/v1/me

↩︎Response guide — what comes back & what each value means24 fields

200 OK. Body is the standard { data } envelope wrapping the current user's profile; no Set-Cookie. Internal columns such as the password hash are never returned. Since §153 the profile also carries the IN-FLIGHT credential changes (pendingEmail, pendingPhone, pendingChanges[]) — email / phone keep naming the values that still sign in — plus hasPassword (can a step-up start at all?) and foundedTenantId (should the client offer founding an organization?). PUT /v1/me/display-name and PUT /v1/me/login-mode answer with this same shape.

data.idUUIDalways

The authenticated user's unique identifier. Use to reference this identity in subsequent calls.

data.emailstring | nullalways

The email that SIGNS IN now (NFC-normalized), or null on a phone-only account. An in-flight email change never alters it — the new address sits in pendingEmail until it applies. May be unverified; check emailVerifiedAt.

data.pendingEmailstring | nullalways

The new address of a live email change (awaiting its code, or held until effectiveAt), or null. It never signs in while pending (scenario 30).

data.pendingPhonestring | nullalways

The new number of a live phone change, or null (scenario 31). Never signs in while pending.

data.pendingChangesCredentialChange[]always

Every LIVE change row (awaiting_verification or held), so a client can offer resend and cancel without a second call; [] when nothing is in flight. Full history is GET /v1/me/credential-changes (scenario 36).

data.pendingChanges[].idUUIDalways

The change row's id. Not needed to act on it — verify / resend / cancel address the caller's ONE live change of that kind (/v1/me/email-change, /v1/me/phone-change, /v1/me/password-change), never an id.

data.pendingChanges[].kindenumalways

Which credential the change replaces. At most one live change per kind; email beside phone only when both are strong, and a password change never sits beside a contact change.

email — An email change (scenario 30) — the code went to the NEW address; confirm at POST /v1/me/email-change/verify.
phone — A phone add or replacement (scenario 31) — the WhatsApp/SMS code went to the NEW number; confirm at POST /v1/me/phone-change/verify.
password — A password change (scenario 35) — the code went to the CURRENT value of the loginMode channel; confirm at POST /v1/me/password-change/verify. value is always null.

data.pendingChanges[].valuestring | nullalways

The target address / number this change would install. null for the password kind (never echoed) and for a closed contact change. Until the row is applied it does NOT sign in — the current value on the profile still does.

data.pendingChanges[].statusenumalways

Where the change stands. Only the two LIVE statuses appear in pendingChanges[] — closed rows are in GET /v1/me/credential-changes.

awaiting_verification — The code is out and not yet confirmed. Next: the matching …/verify with the code, …/resend for a fresh one (the old code dies), or DELETE to cancel. The current value keeps signing in. Lapses to expired after CONTACT_CHANGE_PENDING_TTL_SECONDS (24 h).
held — Contact changes only: the code was confirmed on PASSWORD assurance, so the change waits CONTACT_CHANGE_HOLD_SECONDS (3 days) and worker job J7 applies it at effectiveAt. Every verified current channel was sent contact_change_held with a cancel link (POST /v1/auth/credential-change/cancel); DELETE also still cancels it. The current value keeps signing in until then.
applied — In effect: the new email / phone is the verified credential (user.upserted projected across the user's tenants), or the new password is set and every session has ended. Terminal.
cancelled — Cancelled by the user (DELETE on the change route, DELETE /v1/me/credential-changes) or through the notice link. The current value was never touched. Terminal.
expired — Never confirmed within the pending TTL; closed by J7 with no notice. Terminal — start a new change (and a new step-up) to try again.
failed — At verify the target address / number had meanwhile been taken by another account; contact_change_failed was sent. Terminal.

data.pendingChanges[].assuranceenumalways

The assurance of the step-up token the request spent — it decides what verify does.

password — Only the current password was proven: a contact change is HELD after its code (3-day window, cancel link sent to every verified channel at request and at hold). A password change needs no more than this.
strong — A second factor was proven at POST /v1/me/step-up/{challengeId}/verify: a contact change APPLIES the moment its code is confirmed, and nothing is sent at request.

data.pendingChanges[].requestedAtISO-8601always

When the change was requested.

data.pendingChanges[].verifiedAtISO-8601 | nullalways

When the code was confirmed; null while awaiting_verification and on a change that never got that far.

data.pendingChanges[].effectiveAtISO-8601 | nullalways

When a HELD change applies (verifiedAt + CONTACT_CHANGE_HOLD_SECONDS) — show it as "takes effect on …". null when there is no hold.

data.pendingChanges[].expiresAtISO-8601always

When an unconfirmed change lapses to expired (requestedAt + CONTACT_CHANGE_PENDING_TTL_SECONDS, 24 h).

data.pendingChanges[].codeExpiresAtISO-8601 | nullalways

When the CURRENT code dies (email 15 min, phone 5 min). Past it, …/resend — the change itself is still live until expiresAt.

data.pendingChanges[].codeSentTostring | nullalways

Where the code went, masked (b•••@new.id, +62 812••••21) — the new value for a contact change, the loginMode channel for a password change.

data.displayNamestringalways

The user's human-readable display name. Changed only through PUT /v1/me/display-name (scenario 28).

data.hasMfaEnabledbooleanalways

Whether the user has multi-factor authentication enabled. Drives whether to surface MFA management options.

true — MFA is enabled — disabling it or regenerating recovery codes needs a STRONG step-up (scenario 27).
false — MFA is not enabled; POST /v1/me/mfa/recovery-codes would answer 409.

data.hasPasswordbooleanalways

Whether a password is set — the boolean only, never the hash. Every profile change starts by proving the current password at POST /v1/me/step-up.

true — Profile changes are available: start with POST /v1/me/step-up.
false — A passwordless (phone-only) account: step-up answers 409 no_password, so send the user through the reset flow (scenario 34) to set one first.

data.emailVerifiedAtISO-8601 | nullalways

When the current email was verified, or null. A pending email change does not reset it; it is re-stamped only when the change applies.

data.phonestring | nullalways

The E.164 phone that signs in now, or null on an email-only account. A pending phone change never alters it. Check phoneVerifiedAt before treating it as a usable channel.

data.phoneVerifiedAtISO-8601 | nullalways

When the phone was verified, or null. A verified phone is the prerequisite for phone-OTP MFA (scenario 25) and for loginMode: phone (scenario 33).

data.loginModeenumalways

The account's PRIMARY channel — set at registration (phone sign-up / phone invitation → phone; email → email) and changed only by PUT /v1/me/login-mode on a strong step-up (scenario 33). It is also where a password-change code goes.

email — Signs in at scenario 9 (email + password); a new-device challenge arrives as an email code.
phone — Signs in at scenario 10 (phone + password); a new-device challenge arrives as a phone OTP — which is why DELETE /v1/me/phone answers 409 last_credential until this is switched back to email.

data.foundedTenantIdUUID | nullalways

The LIVE, active organization this identity founded (tenants.created_by = you), or null — the same predicate POST /v1/me/organizations enforces. null → offer "found your organization" (scenario 24); non-null → that route can only 409 organization_already_owned, so offer a way into this tenant instead. Founding is not membership: an admin seat elsewhere never sets it, and a founder who left their own organization still sees it.

POST/v1/me/step-upauthStart a step-up for phone_change

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). AN ADD IS THE SAME ROUTE AS A REPLACE, AND IS HELD JUST AS LONG — the three-day hold on a password-only change is not waived because there is nothing to overwrite; what differs is only that there is no old number to notify or to keep signing in.

⛓ Needs an out-of-band value?

🔐 Step-upSend to open a challenge — its challengeId and token are captured for the cards below

Request body (JSON)

ℹ︎Field guide — what each value means & where it comes from2 fields

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.

actionbodyenumrequiredyou choose

The ONE profile action this step-up is for. You pick it to match the card that will spend the token — a token minted for one action is refused by every other (401 step_up_required). The concurrency rules run HERE too, so a blocked action is refused before a token is minted.

display_name — For PUT /v1/me/display-name (scenario 28). passwordOnlyAllowed: true — the password token is enough. Never blocked by a live change.
email_change — For POST /v1/me/email-change (scenario 30). passwordOnlyAllowed: true on an account WITHOUT confirmed TOTP; false with one, and for a second contact change beside a strong one. A PASSWORD-assurance change is HELD 3 days after its code and sends notices with a cancel link; a STRONG one applies at once. Blocked (409 change_in_progress) by a live email or password change, and beside a live phone change unless both are strong.
phone_change — For POST /v1/me/phone-change (scenario 31, and the link-mode add of scenario 4). Same rules as email_change: password enough without confirmed TOTP; held vs applied by assurance; one live phone change at a time, never beside a password change, beside an email change only when both are strong.
password_change — For POST /v1/me/password-change (scenario 35). passwordOnlyAllowed: true. The answer carries loginChannel — the CURRENT loginMode channel the confirmation code will go to, which must be verified (else 409 login_channel_unavailable). Blocked by, and blocks, any live contact change.
login_mode — For PUT /v1/me/login-mode (scenario 33). passwordOnlyAllowed: false — needs a STRONG token. Blocked while ANY credential change is live.
phone_remove — For DELETE /v1/me/phone (no §2 scenario walks this any more — the doc dropped “Removing a phone credential” at its 2026-09-27 revision, while §3.31 and this action stay live). passwordOnlyAllowed: false — needs a STRONG token. Blocked while ANY credential change is live.
mfa_disable — For DELETE /v1/me/mfa (scenario 27). passwordOnlyAllowed: false — needs a STRONG token. Never blocked by a live change.
mfa_recovery_codes — For POST /v1/me/mfa/recovery-codes (scenario 27). passwordOnlyAllowed: false — needs a STRONG token. Never blocked by a live change.

currentPasswordbodystringrequiredyou choose

Your CURRENT account password, 1–1024 chars — the one place in the §153 flows the current password travels; no change body ever carries it again. Wrong → 401 step_up_failed (throttled per user and per session, see above). A phone-only account with no password gets 409 no_password — set one via the reset flow (scenario 34) first. If you do not know the seeded password, the “Set a known password” helper sets one.

Bearer token

Send Authorization: Bearer (no token set!)

→ POST https://api.kerja.team/v1/me/step-up

↩︎Response guide — what comes back & what each value means12 fields

200 OK, { data } envelope, Cache-Control: no-store. The current password was proven for ONE named action, and this is the PASSWORD-assurance step-up token plus the factors that can raise it to strong. Every profile mutation (display name, email / phone / password change, login mode, phone removal, MFA disable, recovery codes) spends one of these tokens — a live session alone is never enough. The tester captures data.challengeId and data.stepUpToken and fills them into the next cards. 401 step_up_failed = wrong password (5 in 15 min → 429; a second throttle trip in 24 h revokes the session); 409 no_password / change_in_progress / login_channel_unavailable refuse BEFORE a token is minted.

data.challengeIdUUIDalways

The step-up challenge. Path parameter of POST /v1/me/step-up/{challengeId}/code and /verify. Lives STEP_UP_CHALLENGE_TTL_SECONDS (600) and takes STEP_UP_MAX_ATTEMPTS (5) wrong codes.

data.stepUpTokenstring (43-char opaque)always

Single-use token bound to this user, this SESSION, this action and password assurance. Spend it on the action's route when passwordOnlyAllowed is true; spending it on another action, from another session or twice → 401 step_up_required. It stays valid alongside the strong token /verify later mints.

data.assuranceenumalways

What the token proves.

password — Always this value here — only the current password has been proven. A strong token comes only from POST /v1/me/step-up/{challengeId}/verify.

data.expiresInnumberalways

Token lifetime in seconds (STEP_UP_TOKEN_TTL_SECONDS, default 300).

data.passwordOnlyAllowedbooleanalways

Whether this token, as minted, already suffices for the action.

true — Spend stepUpToken now: display_name and password_change always; a contact change on an account without confirmed TOTP (that change is then HELD after its code). Raising to strong is still possible and makes a contact change apply at once.
false — Password is not enough: login_mode, phone_remove, mfa_disable, mfa_recovery_codes, and a second contact change beside a strong one. Continue with /code (for a code factor) and /verify to get a strong token.

data.optionsarrayalways

The factors /verify will accept for this challenge. A code factor always goes to the CURRENT value on the account (never a pending one) and only if that value is verified and not young (applied on password assurance inside CHANNEL_TRUST_AGE_SECONDS, 30 days). For a contact change the channel being changed is one option among the others, never the only one.

data.options[].factorenumalways

The factor kind — pass it as factor to /code and /verify.

email_code — A code to the verified current email: send it with /code, then /verify.
phone_code — A WhatsApp/SMS code to the verified current phone: send it with /code, then /verify.
totp — Offered when a confirmed authenticator exists. Nothing to send — go straight to /verify with the app's code.
recovery_code — Offered while unused recovery codes remain. Nothing to send — /verify with one; it is consumed.

data.options[].roleenumconditional

Code factors only: how the channel relates to the action. The list holds whatever is ELIGIBLE and nothing more — an account whose only eligible factor is the channel being changed is offered that alone, and one with no eligible factor at all is offered an EMPTY list and must proceed password-only (accepting the three-day hold on a contact change).

current_value — The channel whose value this very action changes (e.g. the current email in an email change) — proving it confirms the owner of the old value.
other_channel — The account's OTHER verified channel — proving it shows control of a second, independent credential.
channel — The role used for the actions that change no channel value of their own — login_mode, phone_remove and the two MFA actions: every eligible channel is simply offered as a channel. (For phone_remove the phone is still offered as current_value, because that IS the value being removed.)

data.options[].maskedstringconditional

Code factors only: the masked destination (b•••@old.id, +62 812••••21) so the user can choose. Absent for totp / recovery_code.

data.loginChannelobjectconditional

password_change only: where the confirmation code of POST /v1/me/password-change will go — the current value of the loginMode channel, which must be verified (else 409 login_channel_unavailable).

data.loginChannel.channelenumconditional

The sign-in channel.

email — The password-change code will be emailed.
phone — The password-change code will go to the phone by WhatsApp/SMS.

data.loginChannel.maskedstringconditional

The masked destination — show it before the user submits the new password.

POST/v1/me/step-up/{challengeId}/codeauthSend a step-up code to one of the offered channels

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.

🔐 Step-upno challenge yet — start the step-up on the card above

Path parameters

challengeId — filled in from the step-up above

Request body (JSON)

ℹ︎Field guide — what each value means & where it comes from2 fields

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.

challengeIdpathUUIDrequiredauto-captured

The challenge POST /v1/me/step-up just opened — auto-filled from the step-up card on this page (a fresh start supersedes it). Expired, unknown, or another user's → 404 not_found.

factorbodyenumrequiredfrom a response

Which channel to send the code to. Must be one of the challenge's options[] from the step-up answer (else 422 factor_not_eligible) — a code always goes to the CURRENT, verified, not-young value, never to a pending one. For a contact change the channel being changed is one option among the others, never the only one.

email_code — Emails a code to the account's current verified address (~15 min). Retrieve it with the “Get a step-up code” helper (by challengeId).
phone_code — Sends a WhatsApp/SMS code to the account's current verified number (~5 min). Retrieve it with the “Get a step-up code” helper (by challengeId).

Bearer token

Send Authorization: Bearer (no token set!)

→ POST https://api.kerja.team/v1/me/step-up/{challengeId}/code

↩︎Response guide — what comes back & what each value means3 fields

202 Accepted, { data } envelope, Cache-Control: no-store. A step-up code (the step_up.<action> message, in the caller's locale) went to the chosen channel option. The code is bound to THIS challenge; a second send retires the first code. 404 = no such challenge for this caller (or it expired); 422 factor_not_eligible = the factor is not among the challenge's options; 429 = per-user, per-channel throttle.

data.statusenumalways

Send acknowledgement.

accepted — The only value: the code is on its way. Collect it (dev: the step-up OOB helper) and call /verify with the same factor.

data.maskedstringalways

The masked destination the code went to — tell the user which inbox / handset to check.

data.ttlSecondsnumberalways

Seconds the code lives (e.g. 300). Past it, send again.

POST/v1/me/step-up/{challengeId}/verifyauthProve the factor → a STRONG token

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.

⛓ Needs an out-of-band value?

🔐 Step-upno challenge yet — start the step-up on the card above

Path parameters

challengeId — filled in from the step-up above

Request body (JSON)

ℹ︎Field guide — what each value means & where it comes from3 fields

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.

challengeIdpathUUIDrequiredauto-captured

The challenge from POST /v1/me/step-up — auto-filled from the step-up card on this page. Must be the same challenge the code was sent for (…/code binds a code to ONE challenge).

factorbodyenumrequiredfrom a response

Which factor code carries. Must be one of the challenge's options[] (else 422 factor_not_eligible).

email_code — code is the email code sent by …/code with factor email_code. Send …/code first — the “Get a step-up code” helper REPLACES the hash of the code row that send created, so there is nothing to fetch before it.
phone_code — code is the WhatsApp/SMS code sent by …/code with factor phone_code. Same helper, same order: send, then “Get a step-up code”.
totp — code is the current 6-digit TOTP from the enrolled authenticator — use the “Get current TOTP code” helper. Offered only when a CONFIRMED authenticator exists. No …/code send.
recovery_code — code is one of your unused MFA recovery codes (from enrolment or the last regeneration). Offered only while unused codes remain; CONSUMED on success. No …/code send.

codebodystringrequiredout-of-band

The value that proves the chosen factor, trimmed, 1–32 chars: the email / phone code delivered out-of-band (locally via the “Get a step-up code” helper, by challengeId), a live TOTP (“Get current TOTP code”), or a recovery code you saved. Wrong, expired or exhausted → 401 step_up_failed, and each wrong code spends one of the challenge's attempts.

Bearer token

Send Authorization: Bearer (no token set!)

→ POST https://api.kerja.team/v1/me/step-up/{challengeId}/verify

↩︎Response guide — what comes back & what each value means3 fields

200 OK, { data } envelope, Cache-Control: no-store. A second factor was proven (the /code code, a TOTP, or a recovery code — the latter consumed) and this is a STRONG step-up token for the same action. The challenge is closed once it succeeds or its attempts run out. The tester captures data.stepUpToken, which replaces the password-assurance token in the next cards (that earlier token stays valid alongside it). 401 step_up_failed = wrong / expired / exhausted code. Audits step_up_succeeded with stepUpMethod = the factor.

data.stepUpTokenstring (43-char opaque)always

The strong token — single-use, bound to this user, session and action. Spend it on the action's route: required for PUT /v1/me/login-mode, DELETE /v1/me/phone, DELETE /v1/me/mfa and POST /v1/me/mfa/recovery-codes; on an email / phone change it makes the change APPLY at its code rather than be held.

data.assuranceenumalways

What the token proves.

strong — Always this value here: password plus a second factor. Satisfies every step-up-gated action it was minted for.

data.expiresInnumberalways

Token lifetime in seconds (STEP_UP_TOKEN_TTL_SECONDS, default 300).

POST/v1/me/phone-changeauthRequest a phone change (code to the NEW number)

An ADD over a blank or unverified number, or a REPLACEMENT — the phone twin of the email change (scenario 30). stepUpToken is a phone_change token (password or strong), filled in from the step-up above. 202 with the CredentialChange row (status awaiting_verification); a WhatsApp/SMS code (contact_change.phone, 5 min) goes to the NEW number. NOT policy-gated — combinationMode does not block /v1/me credential changes. 409 conflict if the number belongs to another live user (numbers are globally unique) or an Idempotency-Key is reused with another body; 409 change_in_progress under the concurrency rules (one live change per kind; email beside phone only when BOTH are strong; never beside a password change); 409 no_password; 422 unchanged when it is already your verified number; 429 over CREDENTIAL_CHANGE_MAX_PER_DAY (default 5). A PASSWORD-assurance request also sends contact_change_requested to every verified current channel, carrying a sessionless cancel link (scenario 36).

🔐 Step-upno token yet — start the step-up above

Request body (JSON)

ℹ︎Field guide — what each value means & where it comes from3 fields

Requests a phone change (E-9) — an ADD over a blank or unverified number, or a REPLACEMENT. The phone twin of POST /v1/me/email-change: same token rule (phone_change), same concurrency rules, same daily cap, same idempotency header, same CredentialChange response (202, status awaiting_verification). A WhatsApp/SMS code (contact_change.phone, 5 min) goes to the NEW number; the current number (if any) keeps signing in until the change applies. A password-assurance request also sends contact_change_requested with a sessionless cancel link to every verified current channel, and its verify is HELD; a strong one applies at verify. NOT gated by the registration policy — combinationMode does not block /v1/me credential changes. Errors: 401 step_up_required · 409 no_password · 409 change_in_progress · 409 conflict (the number belongs to another account — numbers are globally unique — or a reused Idempotency-Key) · 422 unchanged · 429 daily cap. Walk-through: scenario 31 (and the link-mode add of scenario 4).

Idempotency-KeyheaderUUIDoptionalclient-generated

OPTIONAL and durable — the card offers the input empty, and an empty input sends no header. With a fresh UUID, a retry with the same body replays the stored 202; the same key with another body → 409 conflict.

phonebodyE.164requiredyou choose

The NEW number, which receives the code. E.164 (e.g. +15551234567). Already your verified number → 422 unchanged; belongs to another live account → 409 conflict.

stepUpTokenbodystringrequiredauto-captured

A token minted for phone_change — password assurance or strong; which one decides held-vs-applied at verify. Filled in automatically from the step-up cards on this page. A token minted for another action (e.g. login_mode later in scenario 4) is refused: 401 step_up_required.

Idempotency-Key header — optional; empty sends no header

Bearer token

Send Authorization: Bearer (no token set!)

→ POST https://api.kerja.team/v1/me/phone-change

↩︎Response guide — what comes back & what each value means11 fields

202 Accepted, { data } envelope, Cache-Control: no-store — the CredentialChange row (kind phone, status awaiting_verification). The phone twin of POST /v1/me/email-change (scenario 31, and scenario 4 for linking a phone after email sign-up): an add over a blank or unverified number, or a replacement. A WhatsApp/SMS code (contact_change.phone, 5 min) goes to the NEW number. Same phone_change step-up token rule, same concurrency rules, same daily cap, same Idempotency-Key replay, same refusals (401 step_up_required, 409 no_password / change_in_progress / conflict, 422 unchanged, 429).

data.idUUIDalways

data.kindenumalways

Which credential the change replaces. At most one live change per kind; email beside phone only when both are strong, and a password change never sits beside a contact change.

email — An email change (scenario 30) — the code went to the NEW address; confirm at POST /v1/me/email-change/verify.
phone — A phone add or replacement (scenario 31) — the WhatsApp/SMS code went to the NEW number; confirm at POST /v1/me/phone-change/verify.
password — A password change (scenario 35) — the code went to the CURRENT value of the loginMode channel; confirm at POST /v1/me/password-change/verify. value is always null.

data.valuestring | nullalways

data.statusenumalways

Where the change stands — the field that decides the client's next step.

awaiting_verification — The code is out and not yet confirmed. Next: the matching …/verify with the code, …/resend for a fresh one (the old code dies), or DELETE to cancel. The current value keeps signing in. Lapses to expired after CONTACT_CHANGE_PENDING_TTL_SECONDS (24 h).
held — Contact changes only: the code was confirmed on PASSWORD assurance, so the change waits CONTACT_CHANGE_HOLD_SECONDS (3 days) and worker job J7 applies it at effectiveAt. Every verified current channel was sent contact_change_held with a cancel link (POST /v1/auth/credential-change/cancel); DELETE also still cancels it. The current value keeps signing in until then.
applied — In effect: the new email / phone is the verified credential (user.upserted projected across the user's tenants), or the new password is set and every session has ended. Terminal.
cancelled — Cancelled by the user (DELETE on the change route, DELETE /v1/me/credential-changes) or through the notice link. The current value was never touched. Terminal.
expired — Never confirmed within the pending TTL; closed by J7 with no notice. Terminal — start a new change (and a new step-up) to try again.
failed — At verify the target address / number had meanwhile been taken by another account; contact_change_failed was sent. Terminal.

data.assuranceenumalways

The assurance of the step-up token the request spent — it decides what verify does.

password — Only the current password was proven: a contact change is HELD after its code (3-day window, cancel link sent to every verified channel at request and at hold). A password change needs no more than this.
strong — A second factor was proven at POST /v1/me/step-up/{challengeId}/verify: a contact change APPLIES the moment its code is confirmed, and nothing is sent at request.

data.requestedAtISO-8601always

When the change was requested.

data.verifiedAtISO-8601 | nullalways

When the code was confirmed; null while awaiting_verification and on a change that never got that far.

data.effectiveAtISO-8601 | nullalways

When a HELD change applies (verifiedAt + CONTACT_CHANGE_HOLD_SECONDS) — show it as "takes effect on …". null when there is no hold.

data.expiresAtISO-8601always

When an unconfirmed change lapses to expired (requestedAt + CONTACT_CHANGE_PENDING_TTL_SECONDS, 24 h).

data.codeExpiresAtISO-8601 | nullalways

When the CURRENT code dies (email 15 min, phone 5 min). Past it, …/resend — the change itself is still live until expiresAt.

data.codeSentTostring | nullalways

Where the code went, masked (b•••@new.id, +62 812••••21) — the new value for a contact change, the loginMode channel for a password change.

POST/v1/me/phone-change/resendauthOptional — resend the code to the new number

202 { ttlSeconds } — a fresh code to the new number; the previous code dies. 409 no_pending_change when no phone change is awaiting its code; 429 at 5 per 15 min per change and per destination.

ℹ︎Field guide — what each value means & where it comes fromno inputs

No body. Sends a fresh code to the NEW number (E-11); the previous code dies. 202 { ttlSeconds: 300 }. Auth + throttled (per change and per destination → 429) + no-store. 409 no_pending_change when no phone change is awaiting its code.

Bearer token

Send Authorization: Bearer (no token set!)

→ POST https://api.kerja.team/v1/me/phone-change/resend

↩︎Response guide — what comes back & what each value means1 field

202 Accepted, { data } envelope, Cache-Control: no-store. A fresh code went to the NEW number; the previous one is dead. 409 no_pending_change when no phone change awaits its code; 429 on the per-change / per-destination throttle.

data.ttlSecondsnumberalways

Lifetime of the new code in seconds (300 for phone).

DELETE/v1/me/phone-changeauthOptional — cancel the phone change

204, idempotent, NO step-up — cancelling only ever keeps the current value, so it needs no proof. Works while the change awaits its code or is held; the current phone (if any) is untouched. Every verified current channel is told (contact_change_cancelled) and the cancel link is burnt.

ℹ︎Field guide — what each value means & where it comes fromno inputs

No body. Cancels the live phone change (E-12) — awaiting its code or held. 204, idempotent, NO step-up (cancelling only ever keeps the current value). The current phone, if any, is untouched; every verified current channel receives contact_change_cancelled and the cancel link is burnt.

Bearer token

Send Authorization: Bearer (no token set!)

→ DELETE https://api.kerja.team/v1/me/phone-change

↩︎Response guide — what comes back & what each value meansno body

204 No Content — no body. Cancels the live phone change (awaiting its code or held); idempotent, no step-up. Every verified current channel receives contact_change_cancelled; the cancel link is burnt. The current number, if any, is untouched.

POST/v1/me/phone-change/verifyauthConfirm the code — apply now (strong) or hold (password)

The code sent to the NEW number (4–8 digits). What happens depends on the assurance the REQUEST spent: STRONG → applied now — phone + phoneVerifiedAt are set, user.upserted is projected once per app across your tenants, and a phone_otp MFA method MOVES WITH THE NUMBER (the other channel is told, mfa_phone_moved). PASSWORD → the change is HELD for CONTACT_CHANGE_HOLD_SECONDS (default 3 days): every verified current channel is told when it takes effect and gets 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 number was taken meanwhile (the change is failed). Never mints a session or device trust. A linked, verified phone unlocks phone-OTP MFA (scenario 25) and makes loginMode: phone selectable (scenario 33) — but adding it changes neither on its own. The notice of a password-only add goes to the other verified channel (the email) and carries the sessionless cancel link (scenario 36).

⛓ Needs an out-of-band value?

Request body (JSON)

ℹ︎Field guide — what each value means & where it comes from1 field

Confirms the code sent to the NEW number (E-10): STRONG applies now, PASSWORD holds for 3 days — exactly as the email twin. On apply phone and phoneVerifiedAt are set, user.upserted is projected across tenants, and a phone_otp MFA method MOVES WITH THE NUMBER (the other channel is told with mfa_phone_moved). 200 with the CredentialChange row, applied or held. Never mints a session or grants device trust. Holding a verified phone does NOT change how you sign in — loginMode stays until PUT /v1/me/login-mode (scenario 33). Errors: 401 invalid_code (5th wrong code burns it) · 409 no_pending_change · 409 conflict (the number was taken meanwhile — the change is failed).

codebodystringrequiredout-of-band

The 4–8 digit WhatsApp/SMS code sent to the NEW number by POST /v1/me/phone-change (or the latest resend), ~5 min. Locally, use the “Get a credential-change code” helper with your userId and kind phone (a held or closed change has no code → 404).

Bearer token

Send Authorization: Bearer (no token set!)

→ POST https://api.kerja.team/v1/me/phone-change/verify

↩︎Response guide — what comes back & what each value means11 fields

200 OK, { data } envelope, Cache-Control: no-store — the CredentialChange row, applied or held exactly as POST /v1/me/email-change/verify: a strong request applies now, a password-assurance one is held 3 days (current number keeps signing in, cancel link resent in contact_change_held). On apply, phone and phoneVerifiedAt are set, user.upserted is projected across tenants, and a phone_otp MFA method MOVES with the number (the other channel is told with mfa_phone_moved). Never mints a session. 401 invalid_code, 409 no_pending_change, 409 conflict (number taken meanwhile → failed).

data.idUUIDalways

data.kindenumalways

Which credential the change replaces. At most one live change per kind; email beside phone only when both are strong, and a password change never sits beside a contact change.

email — An email change (scenario 30) — the code went to the NEW address; confirm at POST /v1/me/email-change/verify.
phone — A phone add or replacement (scenario 31) — the WhatsApp/SMS code went to the NEW number; confirm at POST /v1/me/phone-change/verify.
password — A password change (scenario 35) — the code went to the CURRENT value of the loginMode channel; confirm at POST /v1/me/password-change/verify. value is always null.

data.valuestring | nullalways

data.statusenumalways

Where the change stands — the field that decides the client's next step.

awaiting_verification — The code is out and not yet confirmed. Next: the matching …/verify with the code, …/resend for a fresh one (the old code dies), or DELETE to cancel. The current value keeps signing in. Lapses to expired after CONTACT_CHANGE_PENDING_TTL_SECONDS (24 h).
held — Contact changes only: the code was confirmed on PASSWORD assurance, so the change waits CONTACT_CHANGE_HOLD_SECONDS (3 days) and worker job J7 applies it at effectiveAt. Every verified current channel was sent contact_change_held with a cancel link (POST /v1/auth/credential-change/cancel); DELETE also still cancels it. The current value keeps signing in until then.
applied — In effect: the new email / phone is the verified credential (user.upserted projected across the user's tenants), or the new password is set and every session has ended. Terminal.
cancelled — Cancelled by the user (DELETE on the change route, DELETE /v1/me/credential-changes) or through the notice link. The current value was never touched. Terminal.
expired — Never confirmed within the pending TTL; closed by J7 with no notice. Terminal — start a new change (and a new step-up) to try again.
failed — At verify the target address / number had meanwhile been taken by another account; contact_change_failed was sent. Terminal.

data.assuranceenumalways

The assurance of the step-up token the request spent — it decides what verify does.

password — Only the current password was proven: a contact change is HELD after its code (3-day window, cancel link sent to every verified channel at request and at hold). A password change needs no more than this.
strong — A second factor was proven at POST /v1/me/step-up/{challengeId}/verify: a contact change APPLIES the moment its code is confirmed, and nothing is sent at request.

data.requestedAtISO-8601always

When the change was requested.

data.verifiedAtISO-8601 | nullalways

When the code was confirmed; null while awaiting_verification and on a change that never got that far.

data.effectiveAtISO-8601 | nullalways

When a HELD change applies (verifiedAt + CONTACT_CHANGE_HOLD_SECONDS) — show it as "takes effect on …". null when there is no hold.

data.expiresAtISO-8601always

When an unconfirmed change lapses to expired (requestedAt + CONTACT_CHANGE_PENDING_TTL_SECONDS, 24 h).

data.codeExpiresAtISO-8601 | nullalways

When the CURRENT code dies (email 15 min, phone 5 min). Past it, …/resend — the change itself is still live until expiresAt.

data.codeSentTostring | nullalways

Where the code went, masked (b•••@new.id, +62 812••••21) — the new value for a contact change, the loginMode channel for a password change.