TOTPVerify()

edit

Verifies a Time-based One-Time Password (TOTP) code — the 6-digit codes used by authenticator apps like Google Authenticator for two-factor authentication (2FA).

Supports configurable time window for clock skew tolerance.

Requires Extension: Crypto Extension

TOTPVerify( secret=string, code=string, options=struct );

Returns: Boolean

Argument Description
secret
string, required 		edit

Base32-encoded secret
code
string, required 		edit

The TOTP code to verify (typically 6 digits)
options
struct, optional 		edit

Optional struct: window (default 1), digits (default 6), period (default 30), algorithm (SHA1|SHA256|SHA512, default SHA1)

Usage Notes

edit

Always implement rate limiting on your TOTP verification endpoint. A 6-digit code only has 1 million possible values, so without rate limiting an attacker could brute-force it quickly.

The window parameter controls how many time steps either side of the current time are accepted. The default (1) allows one step of clock skew — about 30 seconds in each direction. Setting it to 0 requires exact time synchronisation, while higher values are more forgiving but less secure.

Examples

edit 
// Verify a TOTP code entered by the user during 2FA login
secret = TOTPSecret(); // stored per user at registration time

// In a real app, the code comes from the user's authenticator app
code = "123456"; // user-entered code
isValid = TOTPVerify( secret, code );

// By default, window=1 allows one time step of clock skew (30 seconds either side)
// This handles small clock differences between server and user's device

// Strict verification with no clock skew tolerance
isValid = TOTPVerify( secret, code, { window: 0 } );

// Wider window for systems with known clock drift
isValid = TOTPVerify( secret, code, { window: 2 } );

See also