Integration user guide

Graboxy CAPTCHA integration

The Graboxy CAPTCHA is a challenge based CAPTCHA service that scores user behavior and makes it possible to distinguish automated scripts from real human users. The challenge is motion-based and works similar to the Graboxy 2FA service.

API keys

To use Graboxy CAPTCHA, you need to sign up for an API key pair. The key pair consists of a site key and a secret key. The site key is used to invoke the Graboxy CAPTCHA service. You will need to use this key when executing the Graboxy CAPTCHA on your website. The secret key authorizes communication between your application backend and the Graboxy CAPTCHA server. You will need the secret key to verify the user. The secret key needs to be kept safe, do not share it publicly.

Placement on your website

You can easily place the Graboxy CAPTCHA on your website by performing the steps below:

1. Load the JavaScript code.

You can do this by globally including the bundle:

Load it using JavaScript:


window.onload = () => {
  // Add Graboxy CAPTCHA <script> tag
  const scriptUrl =
    'https://captcha.graboxy.com/graboxy-captcha-iife.min.js';

  const scriptElement = document.createElement('script');
  scriptElement.setAttribute('src', scriptUrl);
  document.head.appendChild(scriptElement);

  scriptElement.onload = () => {
    // Use the Graboxy CAPTCHA
  }
}

Or in a HTML <script> tag in the <head> of the page:

The first approach is recommended.

2. Execute the Graboxy CAPTCHA.

You probably want to execute the Graboxy CAPTCHA on form submissions or other sensitive use cases you wish to protect. In order for this to work, you will need a site key. The Graboxy CAPTCHA is exposed in the global scope and you can access it through the graboxyCaptcha variable. After executing the Graboxy CAPTCHA you will receive a token which can be used to verify the user. We recommend sending the token to your backend server as soon as possible with the request to verify.


// Submission of a form
var form = document.getElementById('form');
form.addEventListener('submit', (event) =&gt; {
  event.preventDefault();

  // Execute the Graboxy CAPTCHA, then handle the token in a callback
  // function
  const captcha = graboxyCaptcha.default.prototype;
  captcha.execute(siteKey).then((token) =&gt; {
    // Do custom actions here
    / ...
    // Send the token to your backend server
  });
});

3. Verify the user.

After executing the Graboxy CAPTCHA, the website displays an onscreen challenge to the user. If the challenge is successfully solved, a token is returned. You can use this token to verify the user. Besides the token that identifies the user, you have to send your secret key along.


data = JSON.stringify({
  "token": "yourCaptchaToken",
  "secret": "secret-key",
});

options = {
  "hostname": "captcha.graboxy.com",
  "port": 443,
  "path": "/api/0/verify",
  "method": "POST",
  "headers": {
    "Content-Type": "application/json",
    "Content-Length": data.length,
  },
};

The response for the verify request will be a JSON object of the following form:


{
  "token": "yourCaptchaToken"                    // The token that identifies
  // the user

  "status": "done" | "failed" | "invalid_token"  // Status of the verification

  "result": "accepted" | "rejected"              // Outcome of the verification
}

Requirements and Limitations

Graboxy CAPTCHA Beta has certain browser, screen resolution and platform limitations. We recommend to turn off the service for unsupported environments.

We support the following desktop browser versions:

Windows 10
- Chrome 94+
- Edge 95
- Firefox 94
Mac
- Chrome 94+
- Edge 95
- Firefox 94
- Safari 14+

We support the following screen resolutions:

1920x1080
1600x900
1536x864
1440x900
1366x768
1280x720

Currently, we do not support mobile platforms, only desktop.

Hide CAPTCHA on mobile devices:

In order to hide Graboxy CAPTCHA on mobile devices, you can display an overlay by including this HTML script:


<div id="mobile-overlay">
  <section>
    <h2>
      Our captcha solution currently only works on desktop browsers.
      <br />
      We’ll launch the mobile version soon, stay tuned
    </h2>
  </section>
</div>

...and by adding the below to your CSS:


#mobile-overlay {
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  bottom: 0;
  background: rgba(0, 0, 0, 0.7);
  display: none;
}

#mobile-overlay section h2 {
  text-align: center;
  font-size: 26px;
  line-height: 40px;
}

@media only screen and (max-width: 768px) {
  #mobile-overlay {
    display: flex;
    justify-content: center;
    align-items: center;
  }
}

Miscellaneous

The Graboxy CAPTCHA tokens have an expiration date of one hour, so please make sure that you verify your user within an hour after executing the CAPTCHA.

Contact Us

Book a Meeting

Let us know how we can help.
Book a free consultation now!

Book Now