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="https://cdn.captchafox.com/api.js"></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:
<html>
<head>
<title>CaptchaFox Demo</title>
<script async defer src="https://cdn.captchafox.com/api.js"></script>
</head>
<body>
<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>
</form>
</body>
</html>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.
https://api.captchafox.com/siteverifyThe API Endpoint expects the following parameters using the application/x-www-form-urlencoded Content-Type.
| POST Parameter | Description |
|---|---|
| secret | The organization secret |
| response | The 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 https://api.captchafox.com/siteverify \
-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 Code | Description |
|---|---|
| missing-input-secret | The secret parameter is missing. |
| invalid-input-secret | The secret parameter is invalid or malformed. |
| missing-input-response | The response parameter is missing. |
| invalid-input-response | The response parameter is invalid or malformed. |
| bad-request | The request is invalid or malformed. |
| timeout-or-duplicate | The 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.