hCaptcha

https://docs.hcaptcha.com
Admin
hCaptcha is a privacy-respecting CAPTCHA service that protects websites and apps from bots, spam,...
Tokens:23,712
Snippets:224
Trust Score:10
Update:3 months ago
Show doc for...
Tokens:
Raw
### Full hCaptcha Protected Signup Form Example

Source: https://docs.hcaptcha.com/

This example demonstrates a complete HTML signup form protected by hCaptcha. Upon successful challenge completion, a hidden token is automatically added to the form for server-side verification.

```html
<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>
```

--------------------------------

### Configure hCaptcha render parameters

Source: https://docs.hcaptcha.com/configuration

Example configuration object passed to the hcaptcha.render method to define sitekey, theme, size, and language.

```json
{
   "sitekey": "your_site_key",
   "theme": "dark",
   "size": "compact",
   "hl": "fr"
}
```

--------------------------------

### hCaptcha Serverless on Fastly Compute@Edge (Rust)

Source: https://docs.hcaptcha.com/integrations

This example demonstrates hCaptcha serverless integration on Fastly Compute@Edge using Rust.

```rust
use fastly::http::{Method, StatusCode};
use fastly::{handle_request, Request, Response};

#[handle_request]
async fn handle_request(req: Request) -> Response {
    if req.get_method() == Method::POST {
        let token = match req.get_body_bytes() {
            Ok(bytes) => String::from_utf8_lossy(&bytes).to_string(),
            Err(_) => return Response::from_status(StatusCode::BAD_REQUEST)
        };
        let secret = std::env::var("HCAPTCHA_SECRET").expect("HCAPTCHA_SECRET must be set");

        let client = reqwest::Client::new();
        let res = client.post("https://hcaptcha.com/siteverify")
            .form(&[
                ("response", token),
                ("secret", secret)
            ])
            .send()
            .await?;

        if res.status().is_success() {
            Response::from_status(StatusCode::OK)
        } else {
            Response::from_status(StatusCode::BAD_REQUEST)
        }
    } else {
        Response::from_status(StatusCode::METHOD_NOT_ALLOWED)
    }
}

```

--------------------------------

### Install hCaptcha TypeScript Types

Source: https://docs.hcaptcha.com/

Install the TypeScript types for the hcaptcha global variable using either yarn or npm.

```bash
yarn add -D @hcaptcha/types
```

```bash
npm install -D @hcaptcha/types
```

--------------------------------

### Full Theme Schema Example

Source: https://docs.hcaptcha.com/custom_themes

This object defines the complete theme schema, including palette and component styles. A subset or single property can be provided for merging with default styles.

```javascript
var theme = {  
  palette: {  
    mode: "light",  
    grey: {  
      100 : "#FAFAFA",  
      200 : "#F5F5F5",  
      300 : "#E0E0E0",  
      400 : "#D7D7D7",  
      500 : "#BFBFBF",  
      600 : "#919191",  
      700 : "#555555",  
      800 : "#333333",  
      900 : "#222222",  
      1000: "#14191F"  
    },  
    primary: {  
      main: "#00838F"  
    },  
    warn: {  
      main: "#EB5757"  
    },  
    text: {  
      heading: "#555555",  
      body   : "#555555"  
    }  
  },  
  component: {  
    checkbox: {  
      main: {  
        fill  : "#FAFAFA",  
        border: "#E0E0E0"  
      },  
      hover: {  
        fill: "#F5F5F5"  
      }  
    },  
    challenge: {  
      main: {  
        fill  : "#FAFAFA",  
        border: "#E0E0E0"  
      },  
      hover: {  
        fill: "#FAFAFA"  
      }  
    },  
    modal: {  
      main: {  
        fill  : "#FFFFFF"  
      },  
      hover: {  
        fill: "#F5F5F5"  
      },  
      focus: {  
        outline: "#0074BF"  
      }  
    },  
    breadcrumb: {  
      main: {  
        fill: "#F5F5F5"  
      },  
      active: {  
        fill: "#00838F"  
      }  
    },  
    button: {  
      main: {  
        fill: "#FFFFFF",  
        icon: "#555555",  
        text: "#555555"  
      },  
      hover: {  
        fill: "#F5F5F5"  
      },  
      focus: {  
        icon   : "#00838F",  
        text   : "#00838F",  
        outline: "#0074BF"  
      },  
      active: {  
        fill: "#F5F5F5",  
        icon: "#555555",  
        text: "#555555"  
      }  
    },  
    link: {  
      focus: {  
        outline: "#0074BF"  
      }  
    },  
    list: {  
      main: {  
        fill  : "#FFFFFF",  
        border: "#D7D7D7"  
      }  
    },  
    listItem: {  
      main: {  
        fill: "#FFFFFF",  
        line: "#F5F5F5",  
        text: "#555555"  
      },  
      hover: {  
        fill: "#F5F5F5"  
      },  
      selected: {  
        fill: "#E0E0E0"  
      },  
      focus: {  
        outline: "#0074BF"  
      }  
    },  
    input: {  
      main: {  
        fill  : "#FAFAFA",  
        border: "#919191"  
      },  
      focus: {  
        fill   : "#F5F5F5",  
        border : "#333333",  
        outline: "#0074BF"  
      }  
    },  
    field: {  
      label: "#222222",  
      input: {  
        main: {  
          border: "#D7D7D7",  
          fill: "#FFFFFF",  
          text: "#14191F"  
        },  
        focus: {  
          outline: "#00838F",  
          fill: "#F5F5F5"  
        },  
        error: {  
          border: "#BF1722",  
          text: "#BF1722"  
        }  
      }  
    },  
    radio: {  
      main: {  
        file  : "#F5F5F5",  
        border: "#919191",  
        check : "#F5F5F5"  
      },  
      selected: {  
        check: "#00838F"  
      },  
      focus: {  
        outline: "#0074BF"  
      }  
    },  
    task: {  
      // Image shown in challenge to be answered  
      main: {  
        fill: "#F5F5F5"  
      },  
      selected: {  
        badge: "#00838F",  
        outline: "#00838F"  
      },  
      report: {  
        badge: "#EB5757",  
        outline: "#EB5757"  
      },  
      details: {  
        heading: '#222222',  
        text: '#222222',  
      },  
      focus: {  
        badge: "#00838F",  
        outline: "#00838F"  
      }  
    },  
    prompt: {  
      main: {  
        fill  : "#00838F",  
        border: "#00838F",  
        text  : "#FFFFFF"  
      },  
      report: {  
        fill  : "#EB5757",  
        border: "#EB5757",  
        text  : "#FFFFFF"  
      }  
    },  
    skipButton: {  
      main: {  
        fill  : "#919191",  
        border: "#919191",  
        text  : "#FFFFFF"  
      },  
      hover: {  
        fill  : "#555555",  
        border: "#919191",  
        text  : "#FFFFFF"  
      },  
      focus: {  
        outline: "#0074BF"  
      }  
    },  
    verifyButton: {  
      main: {  
        fill  : "#00838F",  
        border: "#00838F",  
        text  : "#FFFFFF"  
      },  
      hover: {  

```

--------------------------------

### Configure hCaptcha with single query parameter

Source: https://docs.hcaptcha.com/configuration

Example of forcing a specific localization using the hl parameter.

```html
<script src="https://js.hcaptcha.com/1/api.js?hl=fr" async defer></script>
```

--------------------------------

### Local Development Hosts Entry

Source: https://docs.hcaptcha.com/

Add a hosts entry to circumvent CORS/CORB issues and allow hCaptcha to function correctly during local development. This example uses 'test.mydomain.com'.

```bash
127.0.0.1 test.mydomain.com
```

--------------------------------

### Configure hCaptcha with multiple query parameters

Source: https://docs.hcaptcha.com/configuration

Example of combining multiple parameters using the ampersand separator.

```html
<script  
  src="https://js.hcaptcha.com/1/api.js?hl=es&onload=yourFunction&render=explicit"  
  async  
  defer  
></script>
```

--------------------------------

### Enable and Render hCaptcha with Custom Theme

Source: https://docs.hcaptcha.com/custom_themes

Use this setup to enable custom themes for hCaptcha. Ensure the `custom=true` parameter is added to the script tag and provide a theme object to the `hcaptcha.render` function.

```html
<script src="https://js.hcaptcha.com/1/api.js?render=explicit&onload=onLoad&custom=true" async defer></script>  
  
  <script type="text/javascript">  
  
    var onLoad = function() {  
      hcaptcha.render("h-captcha", {  
        "sitekey": "<sitekey>",  
        "theme"  : {  
          palette: {  
            primary: {  
              main: "#00FF00"  
            },  
            text: {  
              heading: "#454545",  
              body   : "#8C8C8C"  
            }  
          }  
        }  
      });  
    };  
  
  </script>  
```

--------------------------------

### Verify hCaptcha Token in Cloudflare Worker (Rust)

Source: https://docs.hcaptcha.com/integrations

Example of an hCaptcha verify endpoint using Cloudflare Workers written in Rust.

```rust
use worker::*;

#[event(fetch)]
async fn main(req: Request, env: Env, _ctx: Context)
 -> Result<Response> {
    let token = req.json().await?["token"].as_str().unwrap().to_string();
    let secret = env.secret("HCAPTCHA_SECRET")?.get();

    let client = reqwest::Client::new();
    let res = client.post("https://hcaptcha.com/siteverify")
        .form(&[
            ("response", token),
            ("secret", secret)
        ])
        .send()
        .await?;

    if res.status().is_success() {
        Response::ok("hCaptcha verified successfully!")
    } else {
        Response::error("hCaptcha verification failed.", 400)
    }
}

```

--------------------------------

### Verify hCaptcha Token on Server

Source: https://docs.hcaptcha.com/

This Python backend code demonstrates how to verify the hCaptcha token received from the frontend using the hCaptcha API. Ensure you have the 'requests' library installed.

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

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


```

--------------------------------

### Define the explicit render callback

Source: https://docs.hcaptcha.com/configuration

Implement the callback function to initialize the widget after the SDK is ready. Ensure this is defined before the script loads to avoid race conditions.

```javascript
<script type="text/javascript">  
  var yourFunction = function () {  
    console.log('hCaptcha is ready.');  
    var widgetID = hcaptcha.render('captcha-1', { sitekey: 'your_site_key' });  
  };  
</script>
```

--------------------------------

### Test Key Set: Enterprise Account (Safe End User)

Source: https://docs.hcaptcha.com/

For Enterprise customers, use this key set for testing. Ensure the `remoteip` field is sent to `siteverify` to enable all response fields.

```text
Sitekey| `20000000-ffff-ffff-ffff-000000000002`
Secret Key| `0x0000000000000000000000000000000000000000`
Response Token| `20000000-aaaa-bbbb-cccc-000000000002`

```

--------------------------------

### Test Key Set: Enterprise Account (Bot Detected)

Source: https://docs.hcaptcha.com/

Use this Enterprise key set to test bot detection scenarios. Ensure the `remoteip` field is sent to `siteverify` to enable all response fields.

```text
Sitekey| `30000000-ffff-ffff-ffff-000000000003`
Secret Key| `0x0000000000000000000000000000000000000000`
Response Token| `30000000-aaaa-bbbb-cccc-000000000003`

```

--------------------------------

### Test Key Set: Publisher or Pro Account

Source: https://docs.hcaptcha.com/

Use these test keys for automated integration tests. They always generate a passcode without a challenge and are verified with the provided test secret.

```text
Sitekey| `10000000-ffff-ffff-ffff-000000000001`
Secret Key| `0x0000000000000000000000000000000000000000`
Response Token| `10000000-aaaa-bbbb-cccc-000000000001`

```

--------------------------------

### hCaptcha Public Docs Skill Template

Source: https://docs.hcaptcha.com/agent_skills

The core configuration file for the agent skill, defining its name, purpose, and scope guardrails.

```yaml
---
name: hcaptcha-public-docs
description: Reads and cites public hCaptcha docs from docs.hcaptcha.com LLM markdown endpoints with public search-index discovery. Use for non-Enterprise integration, configuration, API, SDK, migration, and troubleshooting requests. If a request is Enterprise-only, hand off to hcaptcha-enterprise-docs.
---
```

--------------------------------

### Backend Testing: Rejected Tokens

Source: https://docs.hcaptcha.com/

Test how your backend handles invalid or expired tokens by sending a nonsense string like 'FAKE-TOKEN' to the `siteverify` endpoint.

```text
FAKE-TOKEN

```

--------------------------------

### Configure hCaptcha via hcaptcha.render()

Source: https://docs.hcaptcha.com/configuration

Use the hcaptcha.render() method to programmatically render the widget with configuration parameters.

```javascript
<script type="text/javascript">  
  hcaptcha.render('your_div_id', // string: ID of target div to render into  
  {  
    sitekey: 'your_site_key',  
    theme: 'dark', // (for example)  
    'error-callback': 'onError', // (for example) string: name of function  
  });  
</script>
```

--------------------------------

### Customize hCaptcha Theme with Palette and Components

Source: https://docs.hcaptcha.com/custom_themes

Create a comprehensive custom theme by defining both palette colors and individual component styles. This allows for detailed control over the widget's appearance.

```javascript
var subtleDarkTheme = {
  palette: {
    mode: "dark",
    grey: {
      100: "#FAFAFA",
      200: "#F5F5F5",
      300: "#E0E0E0",
      400: "#D7D7D7",
      500: "#BFBFBF",
      600: "#919191",
      700: "#787878",
      800: "#5E5E5E",
      900: "#444444",
      1000: "#2A2A2A"
    },
    primary: {
      main: "#607D8B"
    },
    warn: {
      main: "#FF5722"
    },
    text: {
      heading: "#F5F5F5",
      body: "#E0E0E0"
    }
  },
  component: {
    checkbox: {
      main: {
        fill: "#424242",
        border: "#616161"
      },
    },
    input: {
      main: {
        fill: "#424242",
        border: "#616161"
      },
      focus: {
        fill: "#555555",
        border: "#6A6A6A",
        outline: "#607D8B"
      }
    },
    challenge: {
      main: {
        fill: "#303030",
        border: "#424242"
      },
      hover: {
        fill: "#383838"
      }
    },
    button: {
      main: {
        fill: "#424242",
        icon: "#F5F5F5",
        text: "#F5F5F5"
      },
      hover: {
        fill: "#555555"
      },
      focus: {
        icon: "#607D8B",
        text: "#607D8B",
        outline: "#607D8B"
      },
      active: {
        fill: "#555555",
        icon: "#F5F5F5",
        text: "#F5F5F5"
      }
    },
    modal: {
      main: {
        fill: "#222222"
      },
      hover: {
        fill: "#303030"
      },
      focus: {
        outline: "#607D8B"
      }
    }
  }
};

```

--------------------------------

### Search Index Discovery Script

Source: https://docs.hcaptcha.com/agent_skills

A bash and Node.js script to fetch and query the hCaptcha public documentation search index.

```bash
set -euo pipefail

CACHE="${XDG_CACHE_HOME:-$HOME/.cache}/hcaptcha-docs/public-search-index.json"
INDEX="${HCAPTCHA_DOCS_SEARCH_INDEX:-}"
QUERY="${1:-${HCAPTCHA_DOCS_QUERY:-siteverify}}"
[ -s "${INDEX:-}" ] || INDEX="$CACHE"

if [ ! -s "$INDEX" ]; then
  mkdir -p "$(dirname "$CACHE")"
  ID="$(curl -fsSL https://docs.hcaptcha.com/llm/search-cache-id.txt | tr -d '\r\n')"
  curl -fsSL "https://docs.hcaptcha.com/public/index/search-index-${ID}.json" > "$CACHE"
  INDEX="$CACHE"
fi

node - <<'NODE' "$INDEX" "$QUERY"
const fs=require("fs"),[p,q]=process.argv.slice(2),needle=q.toLowerCase();let n=0,seen=new Set();
for(const b of JSON.parse(fs.readFileSync(p,"utf8"))){
  for(const d of b.documents||[]){
    const h=[d.t,d.s,d.u,...(d.b||[])].filter(Boolean).join(" ").toLowerCase();
    if(h.includes(needle)&&!seen.has(d.u)){seen.add(d.u);console.log(`${d.t}\t${d.u}`);if(++n>=20)process.exit(0);}
  }
}
NODE
```

--------------------------------

### Configure hCaptcha for explicit rendering

Source: https://docs.hcaptcha.com/configuration

Include the hCaptcha script with explicit render and onload parameters to defer widget initialization.

```html
<script  
  src="https://js.hcaptcha.com/1/api.js?onload=yourFunction&render=explicit"  
  async  
  defer  
></script>
```

--------------------------------

### Apply hCaptcha themes and sizes

Source: https://docs.hcaptcha.com/configuration

Customize the widget appearance by setting data attributes on the container element.

```html
<div class="h-captcha" data-sitekey="your_site_key" data-theme="dark"></div>
```

```html
<div class="h-captcha" data-sitekey="your_site_key" data-size="compact"></div>
```

--------------------------------

### Customize hCaptcha Theme with Palette

Source: https://docs.hcaptcha.com/custom_themes

Define a custom theme by specifying palette colors. Use this for basic color adjustments.

```javascript
var vibrantTheme = {
  palette: {
    mode: "light",
    grey: { 100: "#FAFAFA", 200: "#F5F5F5", 300: "#E0E0E0", 400: "#D7D7D7", 500: "#BFBFBF", 600: "#919191", 700: "#555555", 800: "#333333", 900: "#222222", 1000: "#14191F" },
    primary: { main: "#FF5722" },
    warn: { main: "#F44336" },
    text: { heading: "#212121", body: "#212121" }
  },
};

```

--------------------------------

### Theme Color Definitions

Source: https://docs.hcaptcha.com/custom_themes

This JSON object defines the color palette for custom themes, including specific colors for fill, border, and text in various states such as main, hover, focus, and disabled.

```json
{
  "widget": {
    "fill": "#00838F",
    "border": "#00838F",
    "text": "#FFFFFF"
  },
  "focus": {
    "outline": "#0074BF"
  },
  "disabled": {
    "fill": "#919191",
    "border": "#919191",
    "text": "#FFFFFF"
  }
},
MFAButton: {
  main: {
    fill: "#00838F",
    border: "#00838F",
    text: "#FFFFFF"
  },
  hover: {
    fill: "#00838F",
    border: "#00838F",
    text: "#FFFFFF"
  },
  focus: {
    outline: "#0074BF"
  }
},
slider: {
  main: {
    bar: "#C4C4C4",
    handle: "#0F8390"
  },
  focus: {
    handle: "#0F8390"
  }
},
textarea: {
  main: {
    fill: "#C4C4C4",
    border: "#919191"
  },
  focus: {
    fill: "#C4C4C4",
    outline: "#0074BF"
  },
  disabled: {
    fill: "#919191"
  }
}
}
```

--------------------------------

### Configure hCaptcha Error Callback

Source: https://docs.hcaptcha.com/configuration

Sets up an error callback function to handle hCaptcha errors during rendering.

```javascript
var onError  = function(err) {  
    console.log("error!", err);  
};  
  
hcaptcha.render('your_div_id', // string: ID of target div to render into  
{  
  sitekey: 'your_site_key',  
  theme: 'dark', // (for example)  
  'error-callback': 'onError', // string: name of function  
});
```

--------------------------------

### hcaptcha.execute(widgetID, options)

Source: https://docs.hcaptcha.com/configuration

Triggers the hCaptcha workflow programmatically, often used in invisible mode.

```APIDOC
## hcaptcha.execute(widgetID, options)

### Description
Triggers the hCaptcha workflow programmatically. Generally used in invisible mode where the target container is a div rather than a button.

### Parameters
- **widgetID** (string) - Optional - Unique ID for a widget. Defaults to first widget created.
- **options** (object) - Optional - Configuration options, such as { async: true } to return a Promise.
```

--------------------------------

### HTML and CSS for Floating hCaptcha Badge

Source: https://docs.hcaptcha.com/invisible

Use this HTML and CSS to create a floating badge that remains visible on the screen. It includes styles for the badge itself and a hidden popup that can be displayed on interaction.

```html
<!DOCTYPE html>
<html>
<head>
  <title>hCaptcha Floating Overlay Image Example</title>
  <style>
    .hcaptcha-overlay-badge {
      position: fixed;
      bottom: 20px;
      right: 20px;
      z-index: 9999;
      cursor: pointer;
    }

    .hcaptcha-overlay-badge img {
      width: 60px;
      height: auto;
    }

    .hcaptcha-overlay-popup {
      display: none;
      position: fixed;
      bottom: 80px;
      right: 20px;
      background-color: #fff;
      border: 1px solid #ccc;
      padding: 10px;
      width: 300px;
      z-index: 9998;
      box-shadow: 0 2px 5px rgba(0, 0, 0, 0.3);
    }


    .content {
        padding: 10%;
    }
  </style>
</head>
<body>

  <div class="hcaptcha-overlay-badge">
    <img src="data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0idXRmLTgiPz4KPCEtLSBHZW5lcmF0b3I6IEFkb2JlIElsbHVzdHJhdG9yIDIzLjAuMiwgU1ZHIEV4cG9ydCBQbHVnLUluIC4gU1ZHIFZlcnNpb246IDYuMDAgQnVpbGQgMCkgIC0tPgo8c3ZnIHZlcnNpb249IjEuMSIgaWQ9IkxheWVyXzEiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgeG1sbnM6eGxpbms9Imh0dHA6Ly93d3cudzMub3JnLzE5OTkveGxpbmsiIHg9IjBweCIgeT0iMHB4IgoJIHZpZXdCb3g9IjAgMCA0ODIuMyA0ODIuMyIgc3R5bGU9ImVuYWJsZS1iYWNrZ3JvdW5kOm5ldyAwIDAgNDgyLjMgNDgyLjM7IiB4bWw6c3BhY2U9InByZXNlcnZlIj4KPHN0eWxlIHR5cGU9InRleHQvY3NzIj4KCS5zdDB7b3BhY2l0eTowLjU7ZmlsbDojMTA3NEJDO2VuYWJsZS1iYWNrZ3JvdW5kOm5ldyAgICA7fQoJLnN0MXtvcGFjaXR5OjAuNztmaWxsOiMxMDc0QkM7ZW5hYmxlLWJhY2tncm91bmQ6bmV3ICAgIDt9Cgkuc3Qye29wYWNpdHk6MC43O2ZpbGw6IzBDODJCRjtlbmFibGUtYmFja2dyb3VuZDpuZXcgICAgO30KCS5zdDN7b3BhY2l0eTowLjg7ZmlsbDojMEM4MkJGO2VuYWJsZS1iYWNrZ3JvdW5kOm5ldyAgICA7fQoJLnN0NHtmaWxsOiMwQzgyQkY7fQoJLnN0NXtvcGFjaXR5OjAuNTtmaWxsOiMwNDhGQkY7ZW5hYmxlLWJhY2tncm91bmQ6bmV3ICAgIDt9Cgkuc3Q2e29wYWNpdHk6MC44O2ZpbGw6IzA0OEZCRjtlbmFibGUtYmFja2dyb3VuZDpuZXcgICAgO30KCS5zdDd7ZmlsbDojMDQ4RkJGO30KCS5zdDh7b3BhY2l0eTowLjc7ZmlsbDojMDE5RUMwO2VuYWJsZS1iYWNrZ3JvdW5kOm5ldyAgICA7fQoJLnN0OXtmaWxsOiMwMTlFQzA7fQoJLnN0MTB7b3BhY2l0eTowLjc7ZmlsbDojMDBBQkJGO2VuYWJsZS1iYWNrZ3JvdW5kOm5ldyAgICA7fQoJLnN0MTF7ZmlsbDojMDBBQkJGO30KCS5zdDEye29wYWNpdHk6MC41O2ZpbGw6IzAyQjhCRTtlbmFibGUtYmFja2dyb3VuZDpuZXcgICAgO30KCS5zdDEze29wYWNpdHk6MC44O2ZpbGw6IzAyQjhCRTtlbmFibGUtYmFja2dyb3VuZDpuZXcgICAgO30KCS5zdDE0e2ZpbGw6IzAyQjhCRTt9Cgkuc3QxNXtvcGFjaXR5OjAuNztmaWxsOiMzMUJEQkE7ZW5hYmxlLWJhY2tncm91bmQ6bmV3ICAgIDt9Cgkuc3QxNntvcGFjaXR5OjAuODtmaWxsOiMzMUJEQkE7ZW5hYmxlLWJhY2tncm91bmQ6bmV3ICAgIDt9Cgkuc3QxN3tmaWxsOiMzMUJEQkE7fQoJLnN0MTh7b3BhY2l0eTowLjU7ZmlsbDojNDdDMEI0O2VuYWJsZS1iYWNrZ3JvdW5kOm5ldyAgICA7fQoJLnN0MTl7b3BhY2l0eTowLjc7ZmlsbDojNDdDMEI0O2VuYWJsZS1iYWNrZ3JvdW5kOm5ldyAgICA7fQoJLnN0MjB7ZmlsbDojRkZGRkZGO30KPC9zdHlsZT4KPHJlY3QgeD0iMzAxLjUiIHk9IjQyMiIgY2xhc3M9InN0MCIgd2lkdGg9IjYwLjMiIGhlaWdodD0iNjAuMyIvPgo8cmVjdCB4PSIyNDEuMiIgeT0iNDIyIiBjbGFzcz0ic3QxIiB3aWR0aD0iNjAuMyIgaGVpZ2h0PSI2MC4zIi8+CjxyZWN0IHg9IjE4MC45IiB5PSI0MjIiIGNsYXNzPSJzdDEiIHdpZHRoPSI2MC4zIiBoZWlnaHQ9IjYwLjMiLz4KPHJlY3QgeD0iMTIwLjYiIHk9IjQyMiIgY2xhc3M9InN0MCIgd2lkdGg9IjYwLjMiIGhlaWdodD0iNjAuMyIvPgo8cmVjdCB4PSIzNjEuOCIgeT0iMzYxLjgiIGNsYXNzPSJzdDIiIHdpZHRoPSI2MC4zIiBoZWlnaHQ9IjYwLjMiLz4KPHJlY3QgeD0iMzAxLjUiIHk9IjM2MS44IiBjbGFzcz0ic3QzIiB3aWR0aD0iNjAuMyIgaGVpZ2h0PSI2MC4zIi8+CjxyZWN0IHg9IjI0MS4yIiB5PSIzNjEuOCIgY2xhc3M9InN0NCIgd2lkdGg9IjYwLjMiIGhlaWdodD0iNjAuMyIvPgo8cmVjdCB4PSIxODAuOSIgeT0iMzYxLjgiIGNsYXNzPSJzdDQiIHdpZHRoPSI2MC4zIiBoZWlnaHQ9IjYwLjMiLz4KPHJlY3QgeD0iMTIwLjYiIHk9IjM2MS44IiBjbGFzcz0ic3QzIiB3aWR0aD0iNjAuMyIgaGVpZ2h0PSI2MC4zIi8+CjxyZWN0IHg9IjYwLjMiIHk9IjM2MS44IiBjbGFzcz0ic3QyIiB3aWR0aD0iNjAuMyIgaGVpZ2h0PSI2MC4zIi8+CjxyZWN0IHg9IjQyMiIgeT0iMzAxLjUiIGNsYXNzPSJzdDUiIHdpZHRoPSI2MC4zIiBoZWlnaHQ9IjYwLjMiLz4KPHJlY3QgeD0iMzYxLjgiIHk9IjMwMS41IiBjbGFzcz0ic3Q2IiB3aWR0aD0iNjAuMyIgaGVpZ2h0PSI2MC4zIi8+CjxyZWN0IHg9IjMwMS41IiB5PSIzMDEuNSIgY2xhc3M9InN0NyIgd2lkdGg9IjYwLjMiIGhlaWdodD0iNjAuMyIvPgo8cmVjdCB4PSIyNDEuMiIgeT0iMzAxLjUiIGNsYXNzPSJzdDciIHdpZHRoPSI2MC4zIiBoZWlnaHQ9IjYwLjMiLz4KPHJlY3QgeD0iMTgwLjkiIHk9IjMwMS41IiBjbGFzcz0ic3Q3IiB3aWR0aD0iNjAuMyIgaGVpZ2h0PSI2MC4zIi8+CjxyZWN0IHg9IjEyMC42IiB5PSIzMDEuNSIgY2xhc3M9InN0NyIgd2lkdGg9IjYwLjMiIGhlaWdodD0iNjAuMyIvPgo8cmVjdCB4PSI2MC4zIiB5PSIzMDEuNSIgY2xhc3M9InN0NiIgd2lkdGg9IjYwLjMiIGhlaWdodD0iNjAuMyIvPgo8cmVjdCB5PSIzMDEuNSIgY2xhc3M9InN0NSIgd2lkdGg9IjYwLjMiIGhlaWdodD0iNjAuMyIvPgo8cmVjdCB4PSI0MjIiIHk9IjI0MS4yIiBjbGFzcz0ic3Q4IiB3aWR0aD0iNjAuMyIgaGVpZ2h0PSI2MC4zIi8+CjxyZWN0IHg9IjM2MS44IiB5PSIyNDEuMiIgY2xhc3M9InN0OSIgd2lkdGg9IjYwLjMiIGhlaWdodD0iNjAuMyIvPgo8cmVjdCB4PSIzMDEuNSIgeT0iMjQxLjIiIGNsYXNzPSJzdDkiIHdpZHRoPSI2MC4zIiBoZWlnaHQ9IjYwLjMiLz4KPHJlY3QgeD0iMjQxLjIiIHk9IjI0MS4yIiBjbGFzcz0ic3Q5IiB3aWR0aD0iNjAuMyIgaGVpZ2h0PSI2MC4zIi8+CjxyZWN0IHg9IjE4MC45IiB5PSIyNDEuMiIgY2xhc3M9InN0OSIgd2lkdGg9IjYwLjMiIGhlaWdodD0iNjAuMyIvPgo8cmVjdCB4PSIxMjAuNiIgeT0iMjQxLjIiIGNsYXNzPSJzdDkiIHdpZHRoPSI2MC4zIiBoZWlnaHQ9I
```

--------------------------------

### Configure hCaptcha via HTML attributes

Source: https://docs.hcaptcha.com/configuration

Use data attributes on the h-captcha div to set the sitekey, theme, and callback functions.

```html
<div  
  class="h-captcha"  
  data-sitekey="your_site_key"  
  data-theme="dark"  
  data-error-callback="onError"  
></div>
```

--------------------------------

### Programmatically Render and Execute hCaptcha

Source: https://docs.hcaptcha.com/

Use this JavaScript code to load the hCaptcha SDK, render an invisible widget, and trigger its execution programmatically. This is useful for custom form submissions or complex workflows.

```javascript
<!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>

```

--------------------------------

### Verify hCaptcha Token with cURL

Source: https://docs.hcaptcha.com/

Use this cURL command to send a POST request to the hCaptcha siteverify API endpoint. Include your secret key, the client's IP address, and the response token for verification.

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

--------------------------------

### Pseudo-code for Server-Side Verification

Source: https://docs.hcaptcha.com/

This pseudo-code outlines the steps to verify an hCaptcha token on your server. It includes retrieving the token from POST data, constructing the payload, and making a POST request to the verification endpoint.

```pseudocode
# 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)  
```
Tokens:
Raw