Verify user MFA setup

Claim one actor/target-bound setup token and conditionally enable only disabled MFA; later storage failure may consume the token.

Outcome

Claim one actor/target-bound setup token and conditionally enable only disabled MFA; later storage failure may consume the token.

These examples prove local handler behavior with real isolated JWT/TOTP/envelope/SQL and explicitly synthetic identity/key dependencies.

Before you start

Verify pinned identity and exact target authority. Cookie identity precedes Bearer identity; self sub/userId or exact management authority is required. An authenticated denial is not proof of expired OAuth.
Use a deliberate private human enrollment/recovery journey. CLI/stdio MCP protects setup secret/token and embedded QR URI, and SDK 0.23.2 protects each backup-code array item separately through a configured protected store. Do not extract protected material, log live codes, use fixture values on real accounts or claim agent credential delivery is proven.
Review exact plans/effects before approval. Stored MFA flags, authenticator enrollment, backup-code delivery/use, session state and notifications are separate outcomes. Tokens are actor/target bound and can be consumed before storage fails; already-enabled state and conditional SQL prevent overwriting active MFA.

Discover the target

topolo whoami --json
topolo apps --json
topolo actions get app_topolo_auth.user_mfa.verify --detail --json

Resolve the actual authenticated self or authorized managed user and read user_security.get for that exact target. Never retrieve a secret/hash for discovery. Supply current TOTP through the intended private authenticator interface, and pass protected setup-token references unchanged.

Input fields

Field	Required	Meaning
`userId`	Yes	Existing Auth user from credential-scoped discovery. Self identity may use sub or userId; another target requires exact management authority over its organization. Cookie identity precedes Bearer identity for these handlers. A valid administrator credential cannot manage a foreign target.
`token`	Yes	Current six-digit TOTP supplied privately by the intended authenticator user. It must match the pending setup secret within the supported current/adjacent 30-second windows. Never copy a fixture code, generate a real code from an extracted secret, log it or retain it as recovery material.
`setupToken`	Yes	Unexpired setup token returned by user_mfa.setup for exactly this user and the same initiating actor. Pass a protected CLI/stdio MCP reference unchanged; do not decode or extract its secret/backup codes. Its jti can be claimed once and a storage failure after claim still consumes it. Releasing a local reference does not revoke an unconsumed server token.

Effects

Claims setup token once before the protected core write; later failure can leave the token consumed.
Enables only a disabled MFA configuration with conditional SQL and hash-only backup codes; does not overwrite a competing active configuration.

Interpret the response

Requires valid setup signature/expiry/type, matching target, exact initiating actor, jti and correct TOTP. An already-enabled target is refused before claim. Correct verification claims jti in session SQL before enabling protected MFA and hash-only backup codes.

The conditional core SQL transition requires mfa_enabled = 0, so a competing enable cannot replace the winning secret/code set. The losing token may already be claimed. If protected storage fails after claim, MFA can remain disabled while the token is consumed; read current status and begin fresh setup rather than retrying the same token.

The successful data identifies userId and mfaEnabled true, without secrets. Require userId to match the reviewed target and verify it through user_security.get, then separately complete a normal intended sign-in challenge. Lifecycle notification and audit are nonfatal; acknowledgment is not delivered notification or actual sign-in proof.

Worked examples

These are complete raw target-handler responses from isolated fixtures, not live or CLI/gateway envelopes. All identifiers, seeds, backup codes and signing keys are synthetic; captured tokens have only a local fixture signature and a fixed already-past lifetime. Never use them for live enrollment. CLI/MCP payloads show the declared request shape and require discovery, private recipient interaction and a reviewed approved plan. SDK 0.23.2 protects each backup-code array item separately through a configured protected store; hosts without one redact sensitive items. Local published-SDK tests do not prove live CLI/MCP or private recipient delivery. A protected setup-token reference must be passed unchanged; no secret extraction or QR reconstruction is authorized by this guide.

Correct TOTP claims one setup token and stores protected MFA plus hash-only backup codes

Input · payload.json:

{
  "userId": "usr_self",
  "token": "845544",
  "setupToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJ0b3BvbG8tYXV0aCIsImF1ZCI6InRvcG9sby1zZXJ2aWNlcyIsInN1YiI6InVzcl9zZWxmIiwiYWN0b3IiOiJ1c3Jfc2VsZiIsInNlY3JldCI6IkpCU1dZM0RQRUhQSzNQWFBKQlNXWTNEUEVIUEszUFhQIiwiYmFja3VwQ29kZXMiOlsiMDAwMDAwMGEiLCIwMDAwMDAwYiIsIjAwMDAwMDBjIiwiMDAwMDAwMGQiLCIwMDAwMDAwZSIsIjAwMDAwMDBmIiwiMDAwMDAwMTAiLCIwMDAwMDAxMSIsIjAwMDAwMDEyIiwiMDAwMDAwMTMiXSwiaWF0IjoxNzkwODk5MjAwLCJleHAiOjE3OTA5MDAxMDAsInR5cGUiOiJtZmFfc2V0dXAiLCJqdGkiOiJiOTNmNDNkYi01ZDFjLTRjODktYjA1NS1hNGQ4MDRkZmIyYjAifQ.4QO9W68TJGEPL7WahVV-Cm1-6hkTN7AdSU0m3XrP9OI"
}

CLI:

topolo actions validate app_topolo_auth.user_mfa.verify --data @payload.json --json
topolo actions plan app_topolo_auth.user_mfa.verify --data @payload.json --confirm --json
topolo actions call app_topolo_auth.user_mfa.verify --data @payload.json --confirm --json

MCP call after validation and plan review:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_auth.user_mfa.verify",
    "input": {
      "userId": "usr_self",
      "token": "845544",
      "setupToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJ0b3BvbG8tYXV0aCIsImF1ZCI6InRvcG9sby1zZXJ2aWNlcyIsInN1YiI6InVzcl9zZWxmIiwiYWN0b3IiOiJ1c3Jfc2VsZiIsInNlY3JldCI6IkpCU1dZM0RQRUhQSzNQWFBKQlNXWTNEUEVIUEszUFhQIiwiYmFja3VwQ29kZXMiOlsiMDAwMDAwMGEiLCIwMDAwMDAwYiIsIjAwMDAwMDBjIiwiMDAwMDAwMGQiLCIwMDAwMDAwZSIsIjAwMDAwMDBmIiwiMDAwMDAwMTAiLCIwMDAwMDAxMSIsIjAwMDAwMDEyIiwiMDAwMDAwMTMiXSwiaWF0IjoxNzkwODk5MjAwLCJleHAiOjE3OTA5MDAxMDAsInR5cGUiOiJtZmFfc2V0dXAiLCJqdGkiOiJiOTNmNDNkYi01ZDFjLTRjODktYjA1NS1hNGQ4MDRkZmIyYjAifQ.4QO9W68TJGEPL7WahVV-Cm1-6hkTN7AdSU0m3XrP9OI"
    },
    "confirm": true
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "MFA enabled successfully",
  "data": {
    "userId": "usr_self",
    "mfaEnabled": true
  },
  "timestamp": "2026-10-02T00:00:00.000Z"
}

Managing actor completes only its own managed-user setup token

Input · payload.json:

{
  "userId": "usr_managed",
  "token": "845544",
  "setupToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJ0b3BvbG8tYXV0aCIsImF1ZCI6InRvcG9sby1zZXJ2aWNlcyIsInN1YiI6InVzcl9tYW5hZ2VkIiwiYWN0b3IiOiJ1c3JfYWRtaW4iLCJzZWNyZXQiOiJKQlNXWTNEUEVIUEszUFhQSkJTV1kzRFBFSFBLM1BYUCIsImJhY2t1cENvZGVzIjpbIjAwMDAwMDBhIiwiMDAwMDAwMGIiLCIwMDAwMDAwYyIsIjAwMDAwMDBkIiwiMDAwMDAwMGUiLCIwMDAwMDAwZiIsIjAwMDAwMDEwIiwiMDAwMDAwMTEiLCIwMDAwMDAxMiIsIjAwMDAwMDEzIl0sImlhdCI6MTc5MDg5OTIwMCwiZXhwIjoxNzkwODk5MzIwLCJ0eXBlIjoibWZhX3NldHVwIiwianRpIjoiMmJiZmI5MzUtZWNlOS00NzM0LWFmZDUtZmRlYTljM2RmZmY1In0.WsxzlnY5hfgU4jdoUam5y9_gndYyK4LUKq8SfPybsW8"
}

CLI:

topolo actions validate app_topolo_auth.user_mfa.verify --data @payload.json --json
topolo actions plan app_topolo_auth.user_mfa.verify --data @payload.json --confirm --json
topolo actions call app_topolo_auth.user_mfa.verify --data @payload.json --confirm --json

MCP call after validation and plan review:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_auth.user_mfa.verify",
    "input": {
      "userId": "usr_managed",
      "token": "845544",
      "setupToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJ0b3BvbG8tYXV0aCIsImF1ZCI6InRvcG9sby1zZXJ2aWNlcyIsInN1YiI6InVzcl9tYW5hZ2VkIiwiYWN0b3IiOiJ1c3JfYWRtaW4iLCJzZWNyZXQiOiJKQlNXWTNEUEVIUEszUFhQSkJTV1kzRFBFSFBLM1BYUCIsImJhY2t1cENvZGVzIjpbIjAwMDAwMDBhIiwiMDAwMDAwMGIiLCIwMDAwMDAwYyIsIjAwMDAwMDBkIiwiMDAwMDAwMGUiLCIwMDAwMDAwZiIsIjAwMDAwMDEwIiwiMDAwMDAwMTEiLCIwMDAwMDAxMiIsIjAwMDAwMDEzIl0sImlhdCI6MTc5MDg5OTIwMCwiZXhwIjoxNzkwODk5MzIwLCJ0eXBlIjoibWZhX3NldHVwIiwianRpIjoiMmJiZmI5MzUtZWNlOS00NzM0LWFmZDUtZmRlYTljM2RmZmY1In0.WsxzlnY5hfgU4jdoUam5y9_gndYyK4LUKq8SfPybsW8"
    },
    "confirm": true
  }
}

Captured local handler response · HTTP 200:

{
  "success": true,
  "message": "MFA enabled successfully",
  "data": {
    "userId": "usr_managed",
    "mfaEnabled": true
  },
  "timestamp": "2026-10-02T00:00:00.000Z"
}

Verify the result

Keep the exact userId from the reviewed input/plan and read user_security.get for that same authorized user. Compare mfa_enabled and has_backup_codes; never retrieve or log secret/hash material.
Stored status is separate from private authenticator enrollment, normal MFA/backup-code sign-in, physical device entries, session invalidation and notification delivery. Verify the intended human journey independently; synthetic local cryptographic fixtures prove none of these live outcomes.

Errors and recovery

Anonymous MFA operation is refused

Captured local refusal · HTTP 401:

{
  "input": {
    "userId": "usr_self",
    "token": "000000",
    "setupToken": "unusable-fixture-setup"
  },
  "response": {
    "success": false,
    "error": {
      "message": "Access token required",
      "code": "AUTH_ERROR",
      "details": null,
      "timestamp": "2026-10-02T00:00:00.000Z"
    }
  }
}

Ordinary user cannot manage another MFA target

Captured local refusal · HTTP 401:

{
  "input": {
    "userId": "usr_managed",
    "token": "000000",
    "setupToken": "unusable-fixture-setup"
  },
  "response": {
    "success": false,
    "error": {
      "message": "Access denied: You can only verify MFA for yourself",
      "code": "AUTH_ERROR",
      "details": null,
      "timestamp": "2026-10-02T00:00:00.000Z"
    }
  }
}

Organization administrator cannot manage a foreign target

Captured local refusal · HTTP 401:

{
  "input": {
    "userId": "usr_foreign",
    "token": "000000",
    "setupToken": "unusable-fixture-setup"
  },
  "response": {
    "success": false,
    "error": {
      "message": "Access denied: You can only verify MFA for yourself",
      "code": "AUTH_ERROR",
      "details": null,
      "timestamp": "2026-10-02T00:00:00.000Z"
    }
  }
}