Update TOTP settings
PUT /v1/security/totp/settings — Store the account's new-device-login and withdraw TOTP preferences. The new-device toggle gates first-login TOTP on a fr
PUT /v1/security/totp/settings
Store the account's new-device-login and withdraw TOTP preferences. The new-device toggle gates first-login TOTP on a fresh browser / CLI. The withdraw flag is stored and echoed on the account, but upstream's withdraw guard does not read it: an account with an authenticator is asked for an authenticator code on every withdrawal regardless, so do not branch a withdraw flow on it. Requires a fresh TOTP code to authenticate the settings change itself.
| Method | PUT |
| Path | /v1/security/totp/settings |
| Auth | Authorization: Bearer <token> required when GATEWAY_AUTH_TOKEN is set |
| Category | auth |
Notes
Failures answer with { error, status, message }, where error is the stable machine code. A rejected second factor maps to one of a stable set: invalid_totp, totp_required, invalid_email_code, email_code_required, verification_locked (too many wrong email codes; the message names the wait), totp_state_conflict (the account is already in the requested state), totp_not_provisioned (no secret generated yet), or rate_limited. Request-shape rejections answer 400 with totp_code_required, totp_and_email_required, or settings_payload_invalid depending on the endpoint. Anything the gateway cannot classify keeps that endpoint's own <action>_failed code with a generic message; the upstream wording stays in the server log.