📱

Verify TOTP Code

Verify time-based one-time passwords with configurable clock drift tolerance.

POST 1 credit /v1/auth/totp-verify

curl -X POST "https://auth.toolkitapi.io/v1/auth/totp-verify" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "JBSWY3DPEHPK3PXP",
    "code": "482193",
    "window": 1
  }'

import httpx

resp = httpx.post(
    "https://auth.toolkitapi.io/v1/auth/totp-verify",
    json={
    "secret": "JBSWY3DPEHPK3PXP",
    "code": "482193",
    "window": 1
  },
)
print(resp.json())

const resp = await fetch("https://auth.toolkitapi.io/v1/auth/totp-verify", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "secret": "JBSWY3DPEHPK3PXP",
    "code": "482193",
    "window": 1
  }),
});
const data = await resp.json();
console.log(data);

# See curl example

Response 200 OK

{
  "valid": true,
  "drift": 0
}

Try It Live

Description

Verify time-based one-time passwords with configurable clock drift tolerance.

How to Use

1

1. Retrieve the user's stored `secret` (Base32-encoded) from your database.

2

2. Collect the `code` the user entered from their authenticator app.

3

3. Set the `window` to control clock drift tolerance (0 for exact match, 1–10 for flexibility).

4

4. Send a POST request and check the `valid` field. If `true`, the code is correct and the user is authenticated.

About This Tool

The Verify TOTP Code endpoint validates a time-based one-time password against a shared secret. It supports configurable clock drift tolerance via the `window` parameter, which specifies how many time steps before and after the current time to accept.

Clock drift is a common issue with TOTP — the user's device clock may be slightly ahead or behind the server. A window of 1 (the default) allows codes from the previous and next 30-second period, covering up to ±30 seconds of drift. The response includes the estimated `drift` in seconds when a match is found outside the exact current period.

This endpoint handles the verification step of two-factor authentication login flows, backup code validation, and step-up authentication for sensitive operations.

Why Use This Tool

2FA login verification — Validate TOTP codes during user login
Step-up authentication — Require TOTP for sensitive operations (password changes, withdrawals)
Backup code validation — Verify one-time backup codes during account recovery
Device trust flows — Validate TOTP before trusting a new device
Administrative access — Require TOTP for admin panel or privileged operations

Frequently Asked Questions

What window value should I use?

A window of 1 is recommended for most applications — it covers ±30 seconds of clock drift while maintaining good security. Increase to 2–3 if your users report frequent failures. Avoid large windows (>5) as they weaken security.

What does the drift value mean?

The `drift` shows the estimated time difference between the user's device clock and the server. A drift of 0 means an exact match. A drift of 30 means the code matched the next time period. You can track drift per user to detect consistently misaligned clocks.

How do I prevent code reuse?

TOTP codes are valid for the duration of the time period (typically 30 seconds). To prevent replay attacks, store the last used code or timestamp per user and reject codes that have already been verified.

What if the user's authenticator shows a different number of digits?

The TOTP secret and code must use the same number of digits. If you generated the secret with `digits=6`, the user's code should be 6 digits. Mismatched digit lengths will always fail verification.

Start using Verify TOTP Code now

Get your free API key and make your first request in under a minute.

Get Free API Key View Docs