Troubleshooting: Verify factor suite (TOTP, push, passkey, backup codes)

The MFA factor suite — TOTP, push, passkeys, and backup codes — proves possession of a secret or device key instead of delivering an OTP, so its failures surface inside your own application’s factor flow rather than on a /verify/send row. Work the symptom map first, then the per-factor cause table. (OTP send/check failures are on the Verify OTP page.)

Symptom map

Symptom	Most likely causes	What to do
Factor enrollment succeeded but the challenge never verifies	The clock skimmed out of the TOTP window, the challenge TTL lapsed before the user responded, or the enrollment captured an artifact (secret, public key) your app later lost	Read the error `reason` in the response `details`; match it in the cause table for that factor
Passkey ceremony returns an attestation or assertion error	The relying party set (`rpId` + origin) you passed at enrollment does not match the domain the ceremony runs on, or the challenge id is reused/stale	Match the error `reason` in the passkey cause table: RP id and origin are pinned at challenge-issue time and re-checked on verify
TOTP code drifted — user types the right digits and gets rejected	Device clock outside the ±1-step (30 s) skew window, or a code the user already used successfully (replay)	Confirm the client clock against NTP before treating enrollment as broken
Push prompt silent — the device never shows the challenge	The factor was revoked, the device key was rotated without re-registration, or the challenge expired in the queue before your app polled it	Issue a fresh `POST /verify/push/factors/{factorId}/challenges` and confirm the factor is still active
Backup code fails or the factor is running dry	The code was already consumed (codes are single-use), or `remaining_count` is at zero	Mint a fresh factor via `POST /verify/factors/backup-codes` or regenerate TOTP recovery codes

Cause table per factor

TOTP (authenticator app)

A rejected TOTP returns INVALID_CODE (422) with either “TOTP code is incorrect or expired” or “Recovery code is invalid or already used”. Creation is immediate — POST /verify/factors/totp returns the otpauth:// URI and secret once, and the factor is live from that response; the first /verify call is what reveals a bad pairing.

Cause	Why it fails	Remediation
Clock drift	The verifier accepts the current 30 s step plus one step either way; a device skewed past ~30 s produces codes outside the window	Sync the device clock to NTP. If you serve users you cannot tell to fix their clock, prompt re-verification with two consecutive codes at enrollment time
Replay	A code that already verified once is rejected — the step counter advances on success	Generate a fresh code; do not reuse the one that just succeeded
Lost or rotated device	The user re-enrolled on a new device and the old factor still exists	Delete the stale factor (`DELETE /verify/factors/totp/{id}`) and create a new one; treat the factor id as disposable, not the identity
Recovery code exhausted or reused	Recovery codes are single-use and hashed at rest; the original plaintext is unrecoverable	Regenerate with `POST /verify/factors/totp/{id}/recovery-codes/regenerate` — this invalidates the old batch and mints ten new codes

Push (device key + signed challenge)

Push failures split into issuing-time and verify-time causes:

Cause	Response	Remediation
Factor revoked	`409 CONFLICT` with `details.reason: "FACTOR_REVOKED"` on challenge issue	Revocation is irreversible — register the device again (`POST /verify/push/factors`) and update your app to the new factor id
Bad device key at registration	`422` with `details.reason: "PUBLIC_KEY_INVALID"`, `ALGORITHM_UNSUPPORTED`, or `KEY_FORMAT_UNSUPPORTED`	Regenerate the key pair on the device and resubmit; the matching private key must never leave the device
Challenge expired in the queue	The challenge TTL (default 120 s, capped at 600 s) passed before the user approved	Issue a new challenge. If your UI asks for approval asynchronously, pass `ttlSeconds` up to 600 and disable the approve button once it lapses
Wrong signing string or nonce	The device signs `factorId.challengeId.nonce`; any deviation fails verification	Sign exactly that concatenation; do not hash or reorder it
Silent device after all of the above	—	Confirm your push-notification path actually reached the device — Orbit validates the signature, but delivering the prompt to the user’s screen is your app’s channel

Passkeys (WebAuthn / FIDO2)

Attestation and assertion verification run server-side; RP id and origin are pinned when the challenge is issued and cross-checked against clientDataJSON on verify, which is what makes a phishing-origin relay fail closed.

Cause	Response	Remediation
Origin / RP-id mismatch	`422` with `details.reason: "ATTESTATION_INVALID"` or `"ASSERTION_INVALID"`	Set the relying party (`rpId`, origin) to your own domain at enrollment and never change it for an existing factor — mismatched RP config is rejected, not adapted. If you renamed your domain, re-enroll affected users
Stale or reused challenge	`409 CONFLICT` with `details.reason: "CHALLENGE_TERMINAL"`, or `410 GONE` with `"CHALLENGE_EXPIRED"`	Each ceremony consumes one challenge; mint a fresh options call per attempt and submit within the TTL (default 300 s, range 30–600)
Wrong ceremony type	`409` `CHALLENGE_WRONG_TYPE` (`expected: "registration"` or `"authentication"`)	Route registration payloads to `/verify/passkey/registration/verify` and assertion payloads to `/verify/passkey/authentication/verify`
Signature / counter check fails	`422` with `ATTESTATION_UNVERIFIED`, or a revoked factor	A counter regression auto-revokes the factor (WebAuthn L3 cloning signal). Tell the user the credential must be re-registered; you cannot override the revoke
Malformed ceremony payload	`422` `ASSERTION_MALFORMED`	Pass the browser’s `navigator.credentials.get()` / `.create()` output back verbatim — do not re-encode or trim fields

Backup codes

Cause	Response	Remediation
Code already consumed	`INVALID_CODE` — the single-use gate rejects a previously matched code	Read `remaining_count` on every successful consume and prompt regeneration at zero
Wrong factor id ↔ user pairing	`INVALID_CODE`	Match the factor id to the user the codes were minted for; codes are not cross-factor

SNA / flashcall possession channels

channel: "sna" and channel: "flashcall" prove possession without an OTP, and both fail closed with 503 SERVICE_UNAVAILABLE and details.reason: "PROVIDER_NOT_WIRED" when their dependency is missing:

Channel	Missing dependency	Remediation
`sna`	No device-bound `device_token` on the send body	Pass the CAMARA token from the client; the endpoint never substitutes one
`flashcall`	No CLI pool provisioned on the tenant	Have your pool provisioned; until then the channel fails closed by design

Data-retention and revoke circuit: reading factor state and re-registering

All factor state is tenant-scoped to your organization, readable through the list endpoints, and removable through the delete/revoke endpoints — re-registration is a client-side flow you own, in line with tenancy being yours to operate:

TOTP / backup codes: list with GET /verify/factors/totp or GET /verify/factors/backup-codes; remove with the matching DELETE (backup-code delete is idempotent).
Push: revoke with POST /verify/push/factors/{factorId}/revoke (irreversible — register a fresh factor after revoking).
Passkeys: revoke with POST /verify/passkey/factors/{factorId}/revoke (idempotent — a second call returns the same response).

Never try to repair a factor in place: delete or revoke it, then run the enrollment ceremony again with the user present. Enrollment secrets (otpauth:// URI, plaintext backup codes) are returned once at creation; if you lost them, the only clean path is re-enrollment.

What not to do

Do not retry a factor challenge unchanged. CHALLENGE_TERMINAL, CHALLENGE_EXPIRED, and FACTOR_REVOKED are state, not rate limits — issue a fresh challenge or re-enroll.
Do not loosen the RP-id / origin to make a failing ceremony pass. The origin cross-check is the phishing resistance; a loosened check is a security regression, not a fix.
Do not disable the passkey counter regression revoke. That signal means the credential was cloned; re-register the credential and tell the user.
Do not treat the 30-minute /check lockout or recipient rate limits as factor problems. Those belong to OTP sends — see Verify OTP.

Escalation packet

If a factor still fails after you have worked the cause table for its type, email support@devotel.io with:

Your tenant id (returned as organizationId by GET /api/v1/me, and shown in the dashboard under Settings → Organization).
The factor id (vftotp_… for TOTP, vfbc_… for backup codes, vpf_… for push, vpk_… for passkeys) of the affected enrollment.
The challenge id (vpc_… for push, vpkc_… for passkeys) of one failing ceremony.
The error code and details.reason from the response envelope, verbatim.

That set lets support trace the exact ceremony through the pinned RP-id / origin, the TTL, and the revocation state without exposing any enrollment secret — never send a TOTP secret, device private key, or passkey credential in an escalation.

Reference

Troubleshooting: Verify factor suite (TOTP, push, passkey, backup codes)

Troubleshooting: Verify factor suite (TOTP, push, passkey, backup codes)

Symptom map

Cause table per factor

TOTP (authenticator app)

Push (device key + signed challenge)

Passkeys (WebAuthn / FIDO2)

Backup codes

SNA / flashcall possession channels

Data-retention and revoke circuit: reading factor state and re-registering

What not to do

Escalation packet

See also

​Troubleshooting: Verify factor suite (TOTP, push, passkey, backup codes)

​Symptom map

​Cause table per factor

​TOTP (authenticator app)

​Push (device key + signed challenge)

​Passkeys (WebAuthn / FIDO2)

​Backup codes

​SNA / flashcall possession channels

​Data-retention and revoke circuit: reading factor state and re-registering

​What not to do

​Escalation packet

​See also

Troubleshooting: Verify factor suite (TOTP, push, passkey, backup codes)

Symptom map

Cause table per factor

TOTP (authenticator app)

Push (device key + signed challenge)

Passkeys (WebAuthn / FIDO2)

Backup codes

SNA / flashcall possession channels

Data-retention and revoke circuit: reading factor state and re-registering

What not to do

Escalation packet

See also