hCaptcha Developer Guide

The hCaptcha widget can protect your applications from bots, spam, and other forms of automated abuse. Installing hCaptcha is fast and easy, but does involve adding some simple HTML and server side code.

To make integration even quicker, wrappers and plugins are available for many frameworks: Angular, Node, Express, ReactJS, VueJS, and more. Created a new one? Let us know!

If you're already using Google's reCAPTCHA, you can use your existing code with a few slight changes. hCaptcha methods are compatible with reCAPTCHA methods, for example render() and onload(). Custom data attributes like theme, size, and tab-index are also supported in the same way by hCaptcha.

Basic Principles

You embed the hCaptcha widget on your site. For example, on a login form. The user answers an hCaptcha. They get a passcode from our server that is embedded in your form. When the user clicks Submit the passcode is sent to your server in the form. Your server then checks that passcode with the hCaptcha server API. hCaptcha says it is valid and credits your account. Your server now knows the user is not a bot and lets them log in. Pretty simple!

Add the hCaptcha Widget to your Webpage

hCaptcha requires two small pieces of client side code to render a captcha widget on an HTML page. First, you must include the hCaptcha javascript resource somewhere in your HTML page. The <script> must be loaded via HTTPS and can be placed anywhere on the page. Inside the <head> tag or immediately after the .h-captcha container are both fine.


<script src="https://hcaptcha.com/1/api.js" async defer></script>

Second, you must add an empty DOM container where the hCaptcha widget will be inserted automatically. The container is typically a <div> (but can be any element) and must have class h-captcha and a data-sitekey attribute set to your public site key.


<div class="h-captcha" data-sitekey="your_site_key"></div>

Typically, you'll want to include the empty .h-captcha container inside an HTML form. When a captcha is successfully solved, a hidden token will automatically be added to your form that you can then POST to your server for verification. You can retrieve it server side with POST parameter h-captcha-response.

Here's a full example where hCaptcha is being used to protect a signup form from automated abuse. When the form is submitted, the h-captcha-response token will be included with the email and password POST data after the captcha is solved.


<html>

  <head>

    <title>hCaptcha Demo</title>

    <script src="https://hcaptcha.com/1/api.js" async defer></script>

  </head>

  <body>

    <form action="" method="POST">

      <input type="text" name="email" placeholder="Email" />

      <input type="password" name="password" placeholder="Password" />

      <div class="h-captcha" data-sitekey="your_site_key"></div>

      <br />

      <input type="submit" value="Submit" />

    </form>

  </body>

</html>

Verify the User Response Server Side

By adding the client side code, you were able to render an hCaptcha widget that identified if users were real people or automated bots. When the captcha succeeded, the hCaptcha script inserted a unique token into your form data. To verify that the token is indeed real and valid, you must now verify it at the API endpoint:


https://hcaptcha.com/siteverify

The endpoint expects a POST request with two parameters: your secret API key and the h-captcha-response token POSTed from your HTML page. You can optionally include the user's IP address as an additional security check.

POST Parameter	Description
secret	Required. Your secret API key.
response	Required. The verification token you received when the user completed the captcha on your site.
remoteip	Optional. The user's IP address.

Tokens can only be used once and must be verified within a short period of time after being issued. To retrieve the token on your server, use the h-captcha-response POST parameter submitted by your form.


# PSEUDO CODE


SECRET_KEY = "your_secret_key"
   # replace with your secret key 

VERIFY_URL = "https://hcaptcha.com/siteverify"


# Retrieve token from post data with key 'h-captcha-response'.

token = request.POST_DATA['h-captcha-response']


# Build payload with secret key and token.

data = { 'secret': SECRET_KEY, 'response': token }


# Make POST request with data payload to hCaptcha API endpoint.

response = http.post(url=VERIFY_URL, data=data)


# Parse JSON from response. Check for success or error codes.

response_json = JSON.parse(response.content)

success = response_json['success']

Your POST request will receive a JSON response. You should check the success field and only execute your normal business logic if success is true. Otherwise, check the error-codes field for a human-readable error code and return an appropriate error message to the end user.

Here's what a JSON response from hCaptcha looks like:


{

   "success": true|false,

   "challenge_ts": timestamp, // timestamp of the captcha (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)

   "hostname": string,        // the hostname of the site where the captcha was solved

   "error-codes": [...]       // optional

}

These are the error codes that can be returned by the hCaptcha API:

Error Code	Description
missing-input-secret	Your secret key is missing.
invalid-input-secret	Your secret key is invalid or malformed.
missing-input-response	The response parameter (verification token) is missing.
invalid-input-response	The response parameter (verification token) is invalid or malformed.
bad-request	The request is invalid or malformed.

Local Development

If you are developing on your local machine there are a few things to keep in mind.

Modern browsers have strict CORS and CORB rules, so opening a file:// URI that loads hCaptcha will not work. Loading hCaptcha from http://localhost/ will encounter the same issue on some browsers. The hCaptcha API also prohibits 'localhost' and '127.0.0.1' as supplied hostnames.

The simplest way to circumvent these issues is to add a hosts entry. For example:


127.0.0.1 test.mydomain.com

Place this in /etc/hosts on Linux, /private/etc/hosts on Mac OS X, or C:\Windows\System32\Drivers\etc\hosts on Windows.

You can then access your local server via http://test.mydomain.com, and everything will work as expected.

Integration Testing: Dummy Keys

If you intend to run automated integration tests that access a live server, the simplest approach is to use the following dummy hCaptcha site key that always generates a passcode without asking a question. Those passcodes can only be verified using the dummy secret.

In the future, when the dummy sitekey is set the hCaptcha widget will warn users visually in order to remind you not to use them in production. The dummy keys provide neither anti-bot protection nor earnings, so please double-check that you use them only in your test environment!


Dummy Site Key:10000000-ffff-ffff-ffff-000000000001


Dummy Secret Key:0x0000000000000000000000000000000000000000

What's next?

Congrats! By following this guide, you now have a complete and working implementation of hCaptcha. By default, hCaptcha supports multiple widgets per page and automatic localization.

If you're interested in a more advanced implementation that involves javascript callbacks, explicit rendering, alternative themes, or explicit localization, check out the next section on configuration. If you're having trouble getting hCaptcha to work on your site, get in touch and let us help.