Getting Started

Getting Started

Integrating CaptchaFox will only take a short amount of time. Follow the steps below to add it to your application.

Get your CaptchaFox keys

Open the CaptchaFox portal

Create an account (opens in a new tab) or login (opens in a new tab) on the CaptchaFox portal

Locate sitekey

Navigate to the Sites tab in the portal and create a new site. Copy the sitekey listed in the configuration.

Locate secret

Navigate to the Organization Settings tab in the portal and copy your secret key.

Integrate the JavaScript Tag

To render a captcha widget on an HTML page with CaptchaFox, two pieces of client-side code are needed. This process is simplified by using our ready-made plugins and libraries.

Select the type of application you want to integrate CaptchaFox into:

Manual Integration

Add the tag to your HTML page

The script tags can be placed inside the head or body tag.

<script async defer src=""></script>

Add the container element

You must add an empty HTML Element to the location where you want the CaptchaFox widget to be rendered. This element (e.g. a <div>) needs the class captchafox and the data-sitekey attribute with your previously copied sitekey.

<div class="captchafox" data-sitekey="YOUR_SITEKEY"></div>

After a successfull captcha verification, a hidden input field containing the response token will be added automatically. This token will then be included in the form data sent to your server when a user submits the form, and can be retrieved on the server side using the POST parameter cf-captcha-response.

The following is an example for a simple HTML page with a form that is protected by CaptchaFox:

    <title>CaptchaFox Demo</title>
    <script async defer src=""></script>
    <form action="YOUR_SERVER_ENDPOINT" method="POST">
      <input type="text" name="email" placeholder="Email" />
      <input type="password" name="password" placeholder="Password" />
      <div class="captchafox" data-sitekey="YOUR_SITEKEY"></div>
      <button type="submit">Submit</button>

Verify the Response Token on the Server

After receiving the response token on the server you need to verify that it is real and valid using the /siteverify API Endpoint. Once issued, tokens can only be used for a single verification and must be authenticated within a short period of time.

The API Endpoint expects the following parameters using the application/x-www-form-urlencoded Content-Type.

POST ParameterDescription
secretThe organization secret
responseThe response token from the widget
sitekey(Optional) The sitekey that was used to issue the token
remoteIp(Optional) IP address of the requesting user

Example using curl:

curl \
  -X POST \
  -d "response=RESPONSE_TOKEN&secret=YOUR_SECRET"

Verification Response

The API Endpoint will respond with a JSON object that tells you whether the CAPTCHA token is valid.

    "success": true|false, // Whether verification succeeded or not
    "challenge_ts": string, // ISO timestamp of the challenge (yyyy-MM-dd'T'HH:mm:ssZZ). Only included on success.
    "hostname": string, // Hostname of the site where the challenge was solved. (Optional)
    "error-codes": [...], // List of error codes. Only included if success is false
    "insights": {...} // Verification details. (Enterprise only)

Receiving a 200 status code from the API does not mean that the verification was successful. Use the returned success field to determine the verification status.

Error Codes

Error CodeDescription
missing-input-secretThe secret parameter is missing.
invalid-input-secretThe secret parameter is invalid or malformed.
missing-input-responseThe response parameter is missing.
invalid-input-responseThe response parameter is invalid or malformed.
bad-requestThe request is invalid or malformed.
timeout-or-duplicateThe response is no longer valid.

Even though we strive to ensure the highest possible availability, downtime or interruptions cannot be ruled out.
In the event of a critical server error, the user should still be able to perform their desired action. We advise that you bypass the request in your own code if the server status code is greater than 200, and logging it as such.