How Server-Side Siteverify Validation Works and Common Token Errors

Cloudflare Turnstile is a tool that validates if a visitor is human by doing a server-side verification. A visitor simply continues browsing while the check happens on its own. This tool works by running background checks on browser signals and behavior, and if the visitor passes the checks, it issues a token to the visitor. The token is a claim by the visitor to prove he/she passed the background check, but the server needs to validate it.

The token is not a proof on its own. A visitor can easily copy a token, replay an old token, or create a random token that resembles a legitimate token. To close this loophole, Server-Side validation is done on your backend. In this case, your server asks Cloudflare if the token is issued by them, if it is fresh, and for your website, and only then does the server trust the request.

How Siteverify Validation Works

Siteverify is a server-side validation tool that verifies if a Turnstile token is issued by them and is fresh for your website.  The flow has four steps. In the first step, the visitor solves a Turnstile challenge and a widget places a token on the page. In the second step, the frontend passes the token, along with a form or request to your server.

In the third step, your server does a POST request to a SiteVerify endpoint and includes your secret key and the token as inputs. The fourth step is where Cloudflare validates the request and sends a JSON object to your server with a success flag, challenge timestamp, hostname, and any error codes.

Why the Secret Key Stays on the Server

The secret key is critical to the security of the trust check and must not appear in browser code. This key resides only on your server and is paired with the site key in the widget. Without the site key, validation fails. In QA testing, this flow is implemented by manual intervention, and this leads to poor velocity. This flow is automated using APIs. For Turnstile, CapMonster Cloud provides an API for Turnstile tokens that provide tokens for test runs, thus enabling a QA pipeline to exercise the complete Submit and Verify flow without manual intervention.

Common Token Errors and What They Mean

The primary causes of token errors are expired tokens, reused tokens and keys that do not match. The SiteVerify response provides an error code array. When a check fails, the error-codes array in the response names the cause, so start there before changing anything.

Error Codes at a Glance

Timeout or Duplicate: The Most Common Failure

A “timeout-or-duplicate” error means a token has timed out or has already been validated. It is a configuration error that uses the same code to represent two different failures. This means that a token that has been validated more than once, or a token that is issued and submitted very quickly, both fail in the same manner.

This error is not an issue with the configuration; the only fix is with the process. With the process, you need to validate each token only once, and immediately after receiving it. Additionally, you can not cache tokens, and each token submission must be done with a new token.

Hostname Checks

A hostname mismatch means a token was issued for a different domain than the one that is validating it. In Siteverify, you can find the hostname for which the token was issued. It is best to validate that against the domain for which the token is being validated. A hostname mismatch can mean that there is a staging secret that is being used against production traffic, or vice versa.

Legitimate Uses for Automated Tokens

Automated tokens can be used for QA testing, legal web scraping, and accessibility testing. Tokens can be used by QA teams to automatically test web forms and flows. Developers can use automated tokens for legal web scraping of publicly available data. Protected forms can be automated to test accessibility.

Conclusion

Turnstile is most commonly used to protect user account forms, which means that validating tokens is the biggest part of Turnstile that protects forms. The widget on the browser captures the signal; however, Siteverify, along with the correct secret key and a valid token, is the only thing that you can trust to make a decision. There are different reasons why a token validation may fail. It is best practice to log those reasons and treat a failure as a rejection.

Test your integration to check failure cases and various edge cases to ensure it works as intended prior to launch. Most integrations work well for normal cases, but fail to integrate properly for edge cases.