switching clears the token & responses
No token
33

Changing your primary sign-in channel

Profile & credentials

An account holding BOTH an email and a verified phone chooses which one is its primary channel. That choice decides which sign-in form applies (scenario 9 vs 10) and, more importantly, which channel a new-device challenge is delivered on. Gated by a STRONG step-up since §153.

  1. GET /v1/me → read the current loginMode (email or phone) and confirm both credentials are verified
  2. POST /v1/me/step-up { action: login_mode, currentPassword }, then …/code and …/verify for a STRONG token
  3. PUT /v1/me/login-mode { loginMode, stepUpToken } → audited login_mode_changed; both verified channels are told
GET/v1/meauthGet my profile

Current profile: email / phone and their *VerifiedAt stamps (null until verified, null entirely on a single-channel account), hasMfaEnabled, loginMode (the primary channel — which sign-in form applies and where a new-device challenge goes), hasPassword (every profile change starts by proving the password, so false means “set one through the reset flow first”), foundedTenantId (the live organization you founded, or null — the read side of the one-per-identity founding cap, scenario 24), and the in-flight changes: pendingEmail / pendingPhone name the new values and pendingChanges carries every LIVE change row (status, masked code destination, code and change expiry, when a held change applies) — scenario 36. email and phone keep naming the values that still log in. The password hash is never returned.

ℹ︎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
→ 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 login_mode

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). For login_mode passwordOnlyAllowed is false — prove a factor below. Refused 409 change_in_progress while ANY credential change is live.

⛓ 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
→ 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
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
→ 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
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
→ 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).
PUT/v1/me/login-modeauthSwitch the primary channel (strong step-up)

loginMode is email or phone; stepUpToken must be a STRONG login_mode token — a password-assurance one is 401 step_up_required, because flipping the channel changes which challenge a future attacker faces and a stolen session could otherwise redirect the new-device code to a channel it controls. 200 with the profile. 409 conflict when the TARGET channel has no verified value (else you could lock yourself out of your own new-device challenge); 409 change_in_progress while ANY credential change is live; 422 unchanged when the account already signs in that way (the token is still spent). CONFLICT IS DECIDED BEFORE UNCHANGED: an account already on email whose email is no longer verified is told 409 conflict, never 422 unchanged — the usability of the target channel is checked first, because that is the answer that tells the caller what to fix. Audited login_mode_changed and both verified channels are told. Sessions and device trust are untouched. login_mode is genuinely new information and cannot be derived: an account with both credentials is otherwise ambiguous at exactly the point the login screen must be chosen. It is set at registration (scenario 3 → phone; scenario 2 and an email invitation → email; a phone invitation → phone).

🔐 Step-upno token yet — start the step-up above
Request body (JSON)
ℹ︎Field guide — what each value means & where it comes from2 fields

Switches the PRIMARY sign-in channel (E-18) — which sign-in form applies and, more importantly, which channel a new-device challenge is delivered on — on a STRONG login_mode step-up token. Auth + no-store; .strict(). 200 with the profile. The TARGET channel must be verified (409 conflict otherwise — else you could lock yourself out of your own new-device challenge); refused 409 change_in_progress while ANY credential change is live (details[0].blocking, scenario 36); 422 unchanged when the account already signs in that way AND that channel is verified — the token is still spent. CONFLICT IS DECIDED FIRST: an account already on a channel that is no longer verified is told 409 conflict, not 422 unchanged, because the usability of the target is what the caller has to fix. Audited login_mode_changed and both verified channels receive a login_mode_changed notice. Nothing is projected; sessions and device trust are untouched. Walk-through: scenario 33 (and the optional last step of scenario 4).

loginModebodyenumrequiredyou choose
The channel the account should sign in with from now on.
  • email — Sign in with email + password (scenario 9); a new-device challenge arrives as an email code (device_email_code), and a password change's confirmation code goes to the email. Refused 409 without a verified email. Switch here BEFORE removing a phone that is the primary channel (§3.31, which no §2 scenario walks any more).
  • phone — Sign in with the E.164 number + password (scenario 10); a new-device challenge arrives as a phone OTP (device_phone_otp), and a password change's code goes to the phone. Refused 409 without a verified phone.
stepUpTokenbodystringrequiredauto-captured
A STRONG token minted for login_mode — the password token from the start card is refused (401 step_up_required), because flipping the channel changes which challenge a future attacker faces and a stolen session could otherwise redirect the new-device code to a channel it controls. Filled in automatically from the step-up cards on this page once …/verify has upgraded it; a token minted for phone_change in the same scenario will NOT do — it is bound to its own action.
Bearer token
→ PUT https://api.kerja.team/v1/me/login-mode
↩︎Response guide — what comes back & what each value means24 fields

200 OK, { data } envelope, Cache-Control: no-store — the PROFILE, the same shape as GET /v1/me, with the new loginMode. Spends a STRONG login_mode step-up token (scenario 33; a password-assurance token is 401 step_up_required). The target channel must be verified (409 conflict otherwise) and NO credential change may be live (409 change_in_progress); asking for the mode already set is 422 unchanged and still spends the token. Both verified channels receive a login_mode_changed notice; nothing is projected; sessions and device trust are untouched. Audits login_mode_changed.

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.