API Docs

Introduction

Thank you for your interest in AuthKong. We are delighted to offer you a robust and user-friendly captcha service designed to enhance your website's security while maintaining a seamless user experience. This documentation is intended to guide you through the process of integrating AuthKong's API into your web applications.

Getting Started

To begin using the AuthKong API, you first need to register your application and obtain a set of public (site) and private (secret) key. These keys are used to authenticate your application when making API requests. You can register your application here.

Your public key is used to load the captcha on your frontend, while your private key is used to verify the captcha on your backend. It is important to keep your private key secure and never expose it to the public.

Frontend Integration

We have a drop-in replacement support for Google's reCAPTCHA. This means that you can easily replace your existing reCAPTCHA implementation with AuthKong's captcha without any significant changes to your frontend code.

To load the captcha on your frontend, you need to include the following script in your HTML file:

<script defer="defer" src="https://captcha.authkong.com/static/challenges/js/api.js"></script>

Defer attribute is optional but recommended. It ensures that the captcha is loaded after the rest of your page has been loaded. This helps to improve your page load speed.

The script tag also supports onload and render attributes. The onload attribute is used to specify a callback function that is executed when the captcha is loaded. The render attribute is used to specify whether the captcha should be rendered automatically or not.

<script defer="defer" src="https://captcha.authkong.com/static/challenges/js/api.js?onload=onloadCallback&render=explicit"></script>

The script tag URL provided is for the Global CDN which is only available for certain plans. For other plans, you need to use the script tag URL provided in your dashboard (often, a country-specific URL such as https://au-captcha.authkong.com/).

The easiest way to load the captcha is to load the default script tag without any attributes. This will automatically load and render the captcha on your page. You must use a DIV element with the class authkong_captcha to render the captcha on your page. The theme can be either light or dark.

<div class="authkong_captcha" data-sitekey="YOUR_SITE_KEY" data-theme="light"></div>

If you have specified a callback function in the onload attribute, the captcha will be loaded but not rendered automatically. You will need to call the render() method to render the captcha on your page. The render() method accepts two parameters: the ID of the DIV element to render the captcha in and configuration options.

let captcha = AuthKongCaptcha.render(document.getElementById("captcha_element"), {
    "sitekey": "YOUR_SITE_KEY",
    "theme": "light", // or dark
    "callback": handleSolution
});

The callback function is executed when the captcha is completed. It receives the captcha response token as its only parameter. You can use this token to verify the captcha on your backend.

function handleSolution(token) {
    // Send token to your backend for verification
}

You can also extract the captcha response token from the DIV element using the getResponse() method or reset the captcha using the reset() method.

console.log("Captcha Response: " + captcha.getResponse());
captcha.reset();

The captcha response is also injected into a hidden input field with the name captcha-response. You can use this input field to submit the captcha response to your backend.

Usage Example

<html>
  <head>
    <title>Example</title>
    <script defer="defer" src="https://captcha.authkong.com/static/challenges/js/api.js"></script>
  </head>
  <body>
    <form action="?" method="POST">
      <div class="authkong_captcha" data-sitekey="YOUR_SITE_KEY" data-theme="light"></div>
      <br/>
      <input type="submit" value="Submit">
    </form>
  </body>
</html>

Backend Integration

To verify the captcha response from your frontend, you'll need to integrate AuthKong's verification API on your server. This process ensures that the response provided by the user is valid and the request is coming from a legitimate source.

First, ensure you have your private (secret) key ready, as this will be used to authenticate the verification request to AuthKong's servers.

When a user submits a form with the AuthKong captcha, your backend should capture the captcha response token from the request. This token is typically found in the 'captcha-response' field, submitted along with your form data.

Next, make a GET or POST request to AuthKong's verification endpoint with the captured token and your private key. The endpoint URL is:

https://verify.authkong.com/

Include the following parameters in your request:

secret: Your private key
response: The captcha response token from the user

These parameters can be included in the body (POST) or in the URL itself (GET).

import requests

# Your private key for AuthKong
private_key = 'your_private_key'

# The captcha response token from the user
captcha_response = 'response_from_frontend'

# AuthKong's verification endpoint
url = 'https://verify.authkong.com/'

# Payload to send in the POST request
payload = {
    'secret': private_key,
    'response': captcha_response
}

# Making the POST request to AuthKong's verification endpoint
response = requests.post(url, data=payload)

# Parsing the response
verification_result = response.json()

# Example of handling the verification result
if verification_result.get('success'):
    print("Captcha verification successful")
else:
    print("Captcha verification failed")

AuthKong's server will respond with a JSON object. This object contains a 'success' boolean indicating whether the captcha was solved correctly.

{
  "success": true,
  "message": "Your captcha response was successfully validated.",
  "error_code": ""
}

Verify the 'success' field to ensure the captcha was solved correctly. Handle the request according to your application's logic – typically, proceeding with the user's requested action if the captcha is valid, or returning an error if it's not.

Ensure that your backend correctly validates the captcha response. Relying solely on frontend validation is not secure, as it can be bypassed by malicious users.

That's it! You've successfully integrated AuthKong's captcha into your web application, enhancing its security while maintaining a user-friendly experience. If you encounter any issues or have further questions, please refer to our detailed API documentation or contact our support team.

Error Code	Message	Success
missing-input-secret	The secret parameter is required.	false
invalid-input-secret	The secret parameter is invalid.	false
missing-input-response	The response parameter is required.	false
invalid-input-response	The response parameter is invalid.	false
timeout-or-duplicate-or-bad-response	We were unable to verify your captcha response. It may have expired or been used already.	false
(none)	Your captcha response was successfully validated.	true

Integration Examples

To make setup easier for you, we have included the backend verification code examples for PHP, Go, Python and NodeJS in a zip file provided below.

Download Now