Let users manage 2FA from your app

Every factor call requires X-Tenant-Id, the app login credential as Authorization: Bearer alcs_…, the raw session bearer as x-session-id, and its signed x-session-activity companion. The session must belong to the same tenant, user pool and application. An API Access machine token or hosted cookie cannot authorize these calls.

Call from your backend and strip the browser Origin header before forwarding: any request carrying Origin is refused with 403 backend_request_required. Forward the end user's User-Agent if you want accurate device names in security notices; without it the notice omits the browser and platform lines rather than naming your backend.

GET /api/v1/auth/account/factors returns the confirmed authenticator, recovery-code metadata, all pool passkey metadata and the available proof methods in one consistent snapshot. Passkeys belong to the pool; only a key on an exact verified origin of this app can be changed through this app. Metadata never includes credential material.

Use the inventory's methods.required_strength: request 2fa for password/email, mfa for an existing authenticator or phr for an eligible app passkey, prefixed by urn:authreads:acr:. A refusal also supplies min_acr. Reverification records evidence on the existing session; it issues no replacement grant.

GET /api/v1/auth/account/factors
x-session-id: <session bearer>
x-session-activity: <signed companion>

POST /api/v1/auth/login/flow/reverify
{"session_id":"<same session bearer>","min_acr":"urn:authreads:acr:2fa"}
# Follow next_method and replace flow_token on each transition.
POST /api/v1/auth/login/flow/verify-email-code
{"flow_token":"<latest flow token>","code":"<user proof>"}
# Completion: session_reverified=true. Keep the original session.

POST /api/v1/auth/account/factors/totp/start
# Show qr_svg/key privately. Start returns the secret once.
POST /api/v1/auth/account/factors/totp/confirm
{"code":"<six-digit authenticator code>"}
# 200 {"recovery_codes":["<ten single-use codes>"]} on first strong-factor binding.
# Subsequent bindings return recovery_codes:null.
# Copy/download privately; require the user to acknowledge saving them.

# A later change needs a new reverify at the current strongest method.
DELETE /api/v1/auth/account/factors/totp

To replace an authenticator, call /totp/start while one is active; /totp/confirm swaps it atomically, so the account is never left without one. No removal is needed first.

The freshness window, setup proof binding, single-use mutation proof and guessing limits are shared with hosted account pages. Start preserves proof for its bound confirmation. A successful change spends it. Fresh email proof cannot remove a current eligible authenticator or passkey. Required policy refuses removal of the last eligible strong factor. Recovery proof is the existing explicit account-recovery exception.

Initial password-only setup remains available inside the sign-in enrolment flow when policy disables email and requires the first strong factor. It does not upgrade authentication assurance: enrolment and authentication are separate steps.

Every passkey operation requires Authreads-Passkey-Origin, the exact verified web or registered native origin. Forward registration options to the client, then its signed WebAuthn credential back to your backend. The server rechecks the domain, app, credential generation, user and session under the mutation lock, including at finish.

All responses use Cache-Control: no-store. No plaintext recovery codes are persisted, logged or audited, and no secret-response cache replays them. First strong-factor binding returns ten codes in flow-v2, API and hosted responses; subsequent bindings return null. Each recovery code works once. Never save codes in localStorage, sessionStorage or a shared server cache.

A retry never issues another set using spent proof. There is no Idempotency-Key: if a success response is lost, read inventory, reverify freshly, then explicitly POST /recovery-codes and show the replacement once. Do not automatically retry mutations. After an operator resets a user's factors, recovery codes are reissued at the user's next strong-factor enrolment. Hosted UI requires acknowledgement before continuing. Factor calls validate activity but do not renew its idle clock; keep using the normal session activity refresh contract.

Test amr membership, never array equality: session evidence can accumulate and ordering is not an authorization rule. Use acr and auth_time to evaluate assurance and freshness. See sessions and the error catalogue.