[email protected] #168457

01767051159 · 2025-08-02T01:47:46Z

01767051159
Aug 2, 2025

title: Developer Guide
slug: /

hCaptcha can help protect your applications from bots, spam, and other forms of automated abuse.

Installing the SDK is fast and easy: either add a few lines of HTML and server side code, or use one of the many tools that natively support hCaptcha.

To make integration quick, plugins and code examples are available for many frameworks: Angular, Node, Express, ReactJS, VueJS, WordPress and many more. Mobile App SDKs are also available.

A complete list of known hCaptcha integrations is also available if you'd like to submit a new one.

Switching from reCAPTCHA

If you're already using Google's reCAPTCHA, you can use your existing code with only a few changes. hCaptcha methods are API-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.

Quick Start

You embed the hCaptcha widget on your site. For example, on a login form.

Frontend code example (simple)

<html>
  <head>
    <script src="https://js.hcaptcha.com/1/api.js" async defer></script>
  </head>
  <body>
    <form method="POST" action="/login">
      <!-- Your other fields (e.g. email, password) go here -->
      <div class="h-captcha" data-sitekey="YOUR_SITE_KEY"></div>
      <br>
      <!-- The hCaptcha flow is triggered and 'h-captcha-response' field
           is automatically sent as a form field upon clicking Submit -->
      <input type="submit" value="Submit">
    </form>
  </body>
</html>

Frontend code example (programmatic JS)

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>hCaptcha Execute Example</title>
  <!-- 1. Load hCaptcha SDK with explicit rendering -->
  <script
    src="https://js.hcaptcha.com/1/api.js?onload=onloadHCaptcha&render=explicit"
    async defer>
  </script>

  <script>
    let widgetId = null;  // will hold the widget ID assigned by hCaptcha

    function onloadHCaptcha() {
      // 2. Once SDK is loaded, render invisible hCaptcha widget
      widgetId = hcaptcha.render('hcaptcha-container', {
        sitekey: 'your_site_key_here',
        size: 'invisible',       // invisible mode
        callback: onSolve,
        'error-callback': onError,
        'expired-callback': onExpired
      });
    }

    function onSolve(token, key) {
      // This function is called after successful solve
      // `token` is the h-captcha-response value
      console.log('hCaptcha solved:', { token, key });
      document.getElementById('demo-form').submit();  // or handle manually
    }

    function onError(err) {
      console.error('hCaptcha error callback:', err);
      // log to analytics, restart flow
    }

    function onExpired() {
      console.warn('hCaptcha token expired');
      // make sure to fetch a new token before user submits form
    }

    function onManualStep(event) {
      event.preventDefault();
      // 3. Trigger the hCaptcha flow programmatically
      if (widgetId === null) {
        console.error('Widget not yet initialized');
      } else {
        hcaptcha.execute(widgetId);
      }
    }
  </script>
</head>
<body>
  <form id="demo-form" action="/submit" method="POST">
    <input type="text" name="name" placeholder="Name" required><br><br>
    <!-- 4. Invisible widget container -->
    <div id="hcaptcha-container"></div><br>
    <button id="submit-btn" onclick="onManualStep(event)">Submit</button>
  </form>
</body>
</html>

The user starts an hCaptcha evaluation: they click the checkbox or submit button, or you trigger it programmatically.
The user gets a token from our server. This is embedded in your form or returned to your JS callback.
The user clicks Submit. The passcode is sent to your server in the form.
Your server sends the token to our API (api.hcaptcha.com/siteverify). hCaptcha says it is valid. Your server now knows the user is not a bot and lets them log in. Pretty simple!

Backend code example

import os
import requests
from flask import Flask, request, jsonify

# URL for token verification
HCAPTCHA_VERIFY_URL = "https://api.hcaptcha.com/siteverify"

# Your secret key from the hCaptcha dashboard
SECRET_KEY = os.getenv("HCAPTCHA_SECRET", "your_secret_here")

app = Flask(__name__)

def verify_hcaptcha_token(token: str, remoteip: str = None) -> dict:
    """
    Sends a POST request to hCaptcha's /siteverify endpoint
    and returns a result dict including 'success' (bool),
    timestamp, hostname, and any error codes returned.
    """
    payload = {
        'secret': SECRET_KEY,
        'response': token
    }

    if remoteip:
        payload['remoteip'] = remoteip  # recommended, improves accuracy

    response = requests.post(HCAPTCHA_VERIFY_URL, data=payload)
    response.raise_for_status()

    data = response.json()
    # Example shape:
    # {
    #   "success": False,
    #   "challenge_ts": "2025-08-01T12:34:56Z",
    #   "hostname": "example.com",
    #   "error-codes": ["invalid-input-response"]
    # }
    return {
        'success': data.get('success', False),
        'challenge_ts': data.get('challenge_ts'),
        'hostname': data.get('hostname'),
        'error_codes': data.get('error-codes', [])
    }

@app.route('/login', methods=['POST'])
def login():
    # 1) Get token from form POST
    token = request.form.get('h-captcha-response')
    if not token:
        return jsonify({'error': 'Missing hCaptcha token'}), 400

    # 2) Verify token via hCaptcha API
    result = verify_hcaptcha_token(token, remoteip=request.remote_addr)

    # 3) Decision logic
    if result['success']:
        # Token valid == allow action
        # Proceed with your login/business logic here
        return jsonify({'status': 'Logged in'}), 200
    else:
        # Verification failed
        return jsonify({
            'error': 'login failed',
            # log error codes from siteverify response
            print('error_codes:', result['error_codes'])
        }), 403

if __name__ == '__main__':
    app.run(debug=True, port=5000)

Request Flow

sequenceDiagram
        participant User
        participant Your Website or App
        participant hCaptcha Client API
        participant Your Server
        participant hCaptcha Siteverify
        User->>Your Website or App: Load Website or App
        Your Website or App->>User: Load hCaptcha JS or SDK
        User->>hCaptcha Client API: Please issue passcode
        hCaptcha Client API->>User: Returns challenge or passcode
        hCaptcha Client API->>Your Website or App: Passcode embedded in form or returned via JS/callback
        Your Website or App->>Your Server: Form or XHR with hCaptcha passcode
        Your Server->>hCaptcha Siteverify: Is this passcode valid?
        hCaptcha Siteverify->>Your Server: Passcode is valid (success is true)
        Your Server->>User: Session authorized, proceed

Content-Security-Policy Settings

Content Security Policy (CSP) headers are an added layer of security that help to mitigate certain types of attacks, including Cross Site Scripting (XSS), clickjacking, and data injection attacks.

If you use CSP headers, please add the following to your configuration:

script-src should include https://hcaptcha.com, https://*.hcaptcha.com
frame-src should include https://hcaptcha.com, https://*.hcaptcha.com
style-src should include https://hcaptcha.com, https://*.hcaptcha.com
connect-src should include https://hcaptcha.com, https://*.hcaptcha.com

Please do not hard-code specific subdomains, like newassets.hcaptcha.com, into your CSP: asset subdomains used may vary over time or by region.

If you are an enterprise customer and would like to enable additional verification to be performed, you can optionally choose the following CSP strategy:

unsafe-eval and unsafe-inline should include https://hcaptcha.com, https://*.hcaptcha.com

Add the hCaptcha Widget to your Webpage

hCaptcha requires two small pieces of client side code to render a 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://js.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 sitekey.

:::info

The sitekey is our unique identifier for your site, app, or flow.

You can set behavior and track statistics per-sitekey. This lets you choose the granularity you need, whether that is a single sitekey used across many sites or one sitekey per flow, e.g. one for signup and one for login.

You were automatically assigned a sitekey when you created an account. We've
included your actual sitekey in all the examples here. It is{' '}
{user.sitekey} and can be found on your{' '}
profile page for
future reference.
:::

Typically, you'll want to include the empty .h-captcha container inside an HTML form. When a challenge is successfully passed, 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 challenge is passed.

<html>
  <head>
    <title>hCaptcha Demo</title>
    <script src="https://js.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 challenge 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://api.hcaptcha.com/siteverify

The endpoint expects a POST request with two parameters: your account secret and the h-captcha-response token sent from your frontend HTML to your backend for verification. Do not send JSON data: the endpoint expects a standard URL-encoded form POST.

Additionally, you should include the user's IP address for enhanced security. While not strictly required, providing the IP address helps improve verification accuracy. For Enterprise customers, this also enables risk scores.

A simple test will look like this:

curl https://api.hcaptcha.com/siteverify \
  -X POST \
  -d "secret=YOUR-SECRET&remoteip=CLIENT-IP&response=CLIENT-RESPONSE"

CLIENT-RESPONSE is the token returned by the hCaptcha SDK to the client.
YOUR-SECRET is your sitekey secret ("ES_...") that you generated in the dashboard.
CLIENT-IP is the client's IP address. While remoteip is not strictly required, providing it helps improve verification accuracy.

The endpoint expects the application/x-www-form-urlencoded Content-Type. You can see exactly what is sent using

curl -vv

in the example above.

Do not use a GET request to call /siteverify. Use a POST request, and pass the parameters in the form body, not the URL.

While the endpoint may respond correctly to a GET request or to a POST request that uses URL parameters, this is not guaranteed. If the parameters you send to GET are too long, the request will fail and you will be unable to validate passcodes. Using a POST request ensures you will not have this problem.

Please note that you must call /siteverify with your account secret in order to validate passcodes users send you are real and unexpired. You will also be unable to validate passcodes from a sitekey in one account if using a different account's secret.

:::info

Since you are logged in, we have included your actual secret key in the
examples here. You can also find it on your{' '}
profile page for
future reference.
:::

POST Parameter	Description
secret	Required. Your account secret key.
response	Required. The verification token you received when the user completed the challenge on your site.
remoteip	Recommended. The user's IP address.
sitekey	Optional. The sitekey you expect to see.

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.

We recommend passing the sitekey parameter, as it will prevent tokens issued on one sitekey from being redeemed elsewhere. Depending on your difficulty settings this might have no security impact, but if you set a higher difficulty level and do not enforce sitekey matches an adversary could potentially solve an easier challenge on another sitekey, then redeem it on a harder one.

# PSEUDO CODE

SECRET_KEY = "your_secret_key"    # replace with your secret key
VERIFY_URL = "https://api.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, or a generic error message if no details are specified in error-codes.

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

{
   "success": true|false,     // is the passcode valid, and does it meet security criteria you specified, e.g. sitekey?
   "challenge_ts": timestamp, // timestamp of the challenge (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
   "hostname": string,        // the hostname of the site where the challenge was passed
   "credit": true|false,      // optional: deprecated field
   "error-codes": [...]       // optional: any error codes
   "score": float,            // ENTERPRISE feature: a score denoting malicious activity.
   "score_reason": [...]      // ENTERPRISE feature: reason(s) for score.
}

(See hCaptcha.com/enterprise for details on hCaptcha Enterprise features like bot scores, passive and nearly passive "No-CAPTCHA" modes, and more.)

Please note that the credit field is not always included, and is scheduled for deprecation in Q3 2023.

Please also note that the hostname field is derived from the user's browser, and should not be used for authentication of any kind; it is primarily useful as a statistical metric. Additionally, in the event that your site experiences unusually high challenge traffic, the hostname field may be returned as "not-provided" rather than the usual value; all other fields will return their normal values.

Siteverify Error Codes Table

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.
expired-input-response	The response parameter (verification token) is expired. (120s default)
already-seen-response	The response parameter (verification token) was already verified once.
bad-request	The request is invalid or malformed.
missing-remoteip	The remoteip parameter is missing.
invalid-remoteip	The remoteip parameter is not a valid IP address or blinded value.
not-using-dummy-passcode	You have used a testing sitekey but have not used its matching secret.
sitekey-secret-mismatch	The sitekey is not registered with the provided secret.

Rotating Your Siteverify Secret

Your siteverify secret is solely for secure machine-to-machine authentication; it should never be exposed publicly.

If your siteverify secret has been unintentionally exposed, you may receive an email warning from us.

You can also rotate it yourself at any time by visiting the Dashboard, choosing your profile icon and Settings menu option, and then clicking Generate New Secret. Make sure to copy that value! We don't retain it, so you won't be able to see it again.

You will receive an email confirmation within a few seconds of rotation.

Note: Free users may rotate the secret once per day. Pro users may rotate secrets up to 3 times per day. Enterprise users have additional options to manage secrets.

For example, Enterprise accounts can create multiple Sitekey Secrets with an optional expiry and assign secrets to one or many sitekeys to enable segmentation of secrets by environment, unique keys per team, and more. Please see the Enterprise docs for more details.

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 [REDACTED] 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, [REDACTED] 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.

TypeScript Types

How to install

You can install our typescript types @hcaptcha/types for the hcaptcha global variable using your preferred package manager:

yarn add -D @hcaptcha/types

or

npm install -D @hcaptcha/types

How to use

Locally

import '@hcaptcha/types';

// `hcaptcha` now is defined on the global object
hcaptcha.execute();

or

///<reference types="@hcaptcha/types"/>

// `hcaptcha` now is defined on the global object
hcaptcha.execute();

Globally

Add import or reference to your .d.ts:

import "@hcaptcha/types";

// or

/// <reference types="@hcaptcha/types"/>

Or add "node_modules/@hcaptcha" to the typeRoots in tsconfig.json

{
  "compilerOptions": {
    // ...
    "typeRoots": [
      "node_modules/@hcaptcha"
    ]
    // ...
  },
  // ...
}

Integration Testing: Test Keys

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

:::caution
The test keys provide no anti-bot protection, so please double-check that you use them only in your test environment!
:::

Test Key Set: Publisher or Pro Account

Test parameter	Value
Sitekey	`10000000-ffff-ffff-ffff-000000000001`
Secret Key	`0x0000000000000000000000000000000000000000`
Response Token	`10000000-aaaa-bbbb-cccc-000000000001`

This keypair will never challenge and always produce the same response token, which will return success: true when passed to the endpoint with this secret. The siteverify response will have the fields found in Publisher and Pro accounts.

If you are an Enterprise customer, please instead use the test keypairs below to ensure you are consuming score and other Enterprise siteverify fields.

Test Key Set: Enterprise Account (Safe End User)

Test parameter	Value
Sitekey	`20000000-ffff-ffff-ffff-000000000002`
Secret Key	`0x0000000000000000000000000000000000000000`
Response Token	`20000000-aaaa-bbbb-cccc-000000000002`

Test Key Set: Enterprise Account (Bot Detected)

Test parameter	Value
Sitekey	`30000000-ffff-ffff-ffff-000000000003`
Secret Key	`0x0000000000000000000000000000000000000000`
Response Token	`30000000-aaaa-bbbb-cccc-000000000003`

For hCaptcha Enterprise users, the two keypairs above will allow you to verify your application behavior in the most common score scenarios. Please contact your integration support engineers for guidance if you have additional questions.

Frontend Testing: Force a Visual Challenge

Sometimes you want to force a visual challenge to make sure everything looks they way you expect when a challenge modal is triggered.

If you are an Enterprise customer, just add a "Challenge" rule targeting your IP or user agent.

If you are using the Pro or free service, one option is to add a second sitekey set to "Always Challenge" mode. Note that "challenge" does not automatically mean "visual challenge" in our system, but if you rapidly reload several times you are likely to start seeing visual challenges.

Backend Testing: Ensure Correct Handling of Rejected Tokens

If the token the user sends to you is invalid or expired, the siteverify response will contain success: false. This means you can safely block the request.

To test this, simply use a nonsense string like "FAKE-TOKEN" in your backend integration tests when you want to validate end-to-end failure behavior.

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.

And if you have any issues getting hCaptcha to work on your site, or you'd like to start a pilot of our enterprise service to try out bot scores, No-CAPTCHA modes, and more, get in touch and we'll be happy to help.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

GitHub Community

[email protected] #168457

Uh oh!

{{title}}

Uh oh!

Replies: 0 comments

Select a reply

Uh oh!

GitHub Community

[email protected] #168457

Uh oh!

01767051159 Aug 2, 2025

title: Developer Guide slug: /

Switching from reCAPTCHA

Quick Start

Frontend code example (simple)

Frontend code example (programmatic JS)

Backend code example

Request Flow

Content-Security-Policy Settings

Add the hCaptcha Widget to your Webpage

Verify the User Response Server Side

Siteverify Error Codes Table

Rotating Your Siteverify Secret

Local Development

TypeScript Types

How to install

How to use

Locally

Globally

Integration Testing: Test Keys

Test Key Set: Publisher or Pro Account

Test Key Set: Enterprise Account (Safe End User)

Test Key Set: Enterprise Account (Bot Detected)

Frontend Testing: Force a Visual Challenge

Backend Testing: Ensure Correct Handling of Rejected Tokens

What's next?

Replies: 0 comments

01767051159
Aug 2, 2025

title: Developer Guide
slug: /