Book a demo

reset_user_mfa

Reset a user's multi-factor authentication

act entity tenant-private since 2026-10-01

Removes every second factor of a user (authenticator app, text message, backup codes) and signs them out everywhere, so they set one up again at their next sign-in. A user is one person across every org they belong to, so the reset is too: an org admin can reset only a user whose every org they administer, and an account owner only a user whose every org is in an account they own. Needs a second factor verified in the last 10 minutes. While a reset is still being carried out, calling it again changes nothing.

Contract

shape
entity
authority
act
evidence
none
subscription
false
permission
any one of: org.admin (carried by the caller's role template in EVERY org the user `user_id` belongs to); account.owner (account role owner or higher in the account of EVERY org the user `user_id` belongs to; an org with no account blocks); a deactivated caller is refused first
idempotency
natural
emits
user.mfa_reset
MCP tool
reset_user_mfa
decision_set
approve, reject, escalate
REST
POST https://api.containertradehq.com/v1/cap/reset_user_mfa

Through MCP this call returns an approval request first; see Approvals.

Idempotency: keyed by the contract's own inputs: the same inputs replay the first call's result

Inputs

nametyperequiredvalidation
user_iduser_idrequiredtradehq-user-id; 1 to 20 characters
The user whose second factors to remove.

Response

  • user_id · string · The user.
  • factors_removed · string[] · The factor kinds Trade HQ held for them and removed: totp, sms, backup_code, passkey.
  • queued · boolean · Whether this call queued the reset in Clerk; false when one was already queued.
Full JSON Schema 
{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20,
      "pattern": "^[A-Za-z0-9_-]{1,20}$",
      "format": "tradehq-user-id",
      "description": "The user.",
      "x-data-class": "operational"
    },
    "factors_removed": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "The factor kinds Trade HQ held for them and removed: totp, sms, backup_code, passkey.",
      "x-data-class": "operational"
    },
    "queued": {
      "type": "boolean",
      "description": "Whether this call queued the reset in Clerk; false when one was already queued.",
      "x-data-class": "operational"
    }
  },
  "required": [
    "user_id",
    "factors_removed",
    "queued"
  ],
  "additionalProperties": false
}

Refusals

The platform refusals apply to every call: version, authentication, authority, validation and rate limits, each in the same envelope.

Surfaces

DesktopF
MobileF
APIF
MCPF*
VoiceD2
PushF
OneBoxN
OutboundN
  • MCP: approval required
  • Voice: degraded: confirmation
  • OneBox: no document originates a reset of second factors
  • Outbound: crosses to no counterparty

Events

Related

None.