Skip to content
POST AI agent ready /v1/totp/validate

TOTP Validate API - Free 2FA Code Verifier

Check whether a TOTP code is valid for a given shared secret. Supports a configurable time window to account for clock skew between client and server.

Parameters

stringrequired

The TOTP code to validate.

stringrequired

The Base32-encoded shared secret.

number

Time step in seconds.

number

Number of periods before and after the current one to accept (for clock skew).

Code examples

curl -X POST https://api.botoi.com/v1/totp/validate \
  -H "Content-Type: application/json" \
  -d '{"code":"482937","secret":"JBSWY3DPEHPK3PXP","period":30,"window":1}'

When to use this API

Login 2FA verification

After a user enters their TOTP code during login, validate it server-side against their stored secret before granting access.

Automated security testing

Generate and validate TOTP codes in integration tests to verify your 2FA middleware rejects expired or incorrect codes.

Frequently asked questions

What does the drift value mean?
Drift indicates the time step offset where the code matched. 0 means the current period, -1 means the previous period, and 1 means the next period.
What window value should I use?
A window of 1 (the default) allows codes from the previous and next 30-second window, which accounts for typical clock skew. Increase to 2 for lenient validation.
Can expired codes pass validation?
Only codes within the time window pass. A window of 1 accepts codes up to 30 seconds old. Codes older than that are rejected.
Is replay protection included?
No. The API performs stateless validation. To prevent replay attacks, track used codes on your server and reject duplicates.

Get your API key

Free tier includes 5 requests per minute with no credit card required. Upgrade for higher limits.