TOTP Two-Factor Authentication Guide: otpauth URI, Algorithms, and Local Debugging

Why You Need TOTP

Passwords alone are not enough — even a strong one from a password generator can be phished or leaked. TOTP (Time-based One-Time Password) adds a rotating code tied to a shared secret and the current time window: without that code, a stolen password is much harder to use.

Industry research (including Google’s) has long shown that 2FA blocks the vast majority of automated account takeovers. For individuals and teams, TOTP is a practical hardening step with a relatively low deployment cost.

Risks of password-only accounts

• Data breaches: databases leak plaintext or hashed passwords
• Phishing: fake login pages harvest credentials
• Brute force: weak passwords fall to dictionaries
• Credential stuffing: one site’s password is tried elsewhere

How TOTP Works

The idea

RFC 6238 builds on HOTP (RFC 4226). The server and client share a secret, each compute HMAC over the current time step, then truncate to 6 or 8 digits. If clocks agree, the codes match.

Apps such as Google Authenticator, Authy, and Microsoft Authenticator are TOTP clients.

Enrollment vs verification

1. Enroll: the server issues a secret (often as a QR code) → the client stores it.
2. Verify: the user submits password + current code → the server recomputes and compares.

Parameters that must match

If algorithm, digits, or period disagree with the issuer, codes will never match — a common bug in hand-rolled integrations.

otpauth URI: what the QR code encodes

Decoded authenticator QR codes are usually Key URIs:

otpauth://totp/Issuer:account?secret=BASE32&issuer=Issuer&algorithm=SHA1&digits=6&period=30

Notes:

• Type must be totp (this guide and our tool focus on TOTP, not HOTP counters).
• secret is Base32; URI algorithm values are SHA1 / SHA256 / SHA512 (no hyphen).
• Path is often Issuer:account; keep the issuer query param aligned to avoid duplicated labels in apps.

For debugging, paste the URI into the local TOTP generator to autofill parameters, or copy a URI back out for phone apps. Unsupported digits (not 6/8) or period (not 30/60) are rejected instead of silently computing the wrong code.

Countdown UX: why the last few seconds matter

Codes die at the window boundary. Remaining seconds are operational:

• ≤5s: the code may expire before the server sees it.
• ≤3s: wait for the next code when you can.

Verifiers that accept ±1 window still help with mild drift; once local clock error approaches a minute, failures become systematic — fix NTP / system time first.

Use cases

High-value accounts

Email, cloud consoles, git hosts, exchanges: enable TOTP (or a hardware key). A compromised mailbox often unlocks password resets elsewhere.

Internal systems

Git, CI/CD, VPN, admin panels: employee password leaks are common; TOTP raises the cost of automated stuffing. Hardware keys are stronger; TOTP remains widely deployed.

Developer debugging

When shipping enrollment/verify flows, a local generator helps you:

• Confirm a Base32 / otpauth payload produces the same codes as a phone app
• Matrix-test SHA-1 / SHA-256 / SHA-512, 6/8 digits, and 30/60s periods
• Submit near the window edge to observe server skew policy

Practical tips

Prefer TOTP over SMS when both exist

SMS faces SIM swap, delay, and number-change churn. If the site supports authenticator apps, bind TOTP.

Save recovery codes

Store Recovery Codes in a password manager or offline safe. A lost phone without codes often means a painful account recovery path.

Audit bindings

Every six months, remove unused entries and spot-check that important accounts still accept codes.

Keep clocks honest

Manual clock changes and long-offline devices are the first suspects when “codes never work.”

Treat cloud-synced authenticators carefully

Cloud sync eases phone swaps and expands the blast radius if the sync account is breached. Local-only apps need a deliberate backup (URI export / secret in a vault).

Implementation notes

ToolVault’s TOTP generator uses Web Crypto HMAC in the browser and is checked against RFC 6238 Appendix B vectors for SHA-1 / SHA-256 / SHA-512. It supports:

• Multiple entries in localStorage (clearing site data drops them — keep an offline secret backup)
• Paste Base32 or otpauth://totp/...; copy URI per entry
• Algorithms SHA-1 / SHA-256 / SHA-512, digits 6/8, period 30/60
• Countdown bar: warn at ≤5s, critical pulse at ≤3s

Secrets never leave the browser — do not trust “online generators” that POST your secret to a server.

FAQ

Why don’t my codes match the phone app?

Check secret (no spaces), algorithm, digits, period, and system time. Any mismatch breaks the whole window.

Is URI SHA1 the same as SHA-1 in the tool?

Yes. Key URIs omit the hyphen; Web Crypto and this tool use SHA-1 internally and convert on import/export.

Can this replace Google Authenticator entirely?

It works as a browser-side backup and debug aid. For important accounts, keep a phone app or hardware key plus recovery codes so one lost device does not lock you out.

Published by ToolVault. More developer tools on the home page.