Quick Start

Get up and running with gkCAPTCHA in under 5 minutes.

1. Create an Account

Sign up at our dashboard to create your account and get your API keys.

2. Create a Site

After signing in, create a new site in your dashboard. You will receive:

  • Site Key: Used in your frontend widget
  • Secret Key: Used for server-side verification (keep this secure!)

3. Install the Widget

Add the script tag once per page. Put the gk-captcha element inside the form you want to protect:

index.html
<script src="https://gkcaptcha.gatekeeper.sa/widget/gk-captcha.js" async defer></script>

<form action="/submit" method="POST">
  <!-- your form fields -->
  <gk-captcha sitekey="pk_live_..."></gk-captcha>
  <button type="submit">Submit</button>
</form>

Optional: react to the result in the page. The token is sent with the form either way.

app.js
const captcha = document.querySelector('gk-captcha');

captcha.addEventListener('captcha-verified', (event) => {
  // The token is also in the form's gk-captcha-token field.
  console.log('Verified:', event.detail.token);
});

captcha.addEventListener('captcha-expired', () => {
  // The token expired. The widget is ready to verify again.
});

captcha.addEventListener('captcha-error', (event) => {
  console.warn('gkCAPTCHA error:', event.detail.code);
});

4. Verify on Server

When the form is sent, read the gk-captcha-token field on your server and verify it. Keep your secret key on the server:

server.js
// On your server (Node.js). Never send your secret key to the browser.
// The form arrives URL-encoded: app.use(express.urlencoded({ extended: false }))
const response = await fetch('https://gkcaptcha.gatekeeper.sa/api/v1/token/verify', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    siteKey: process.env.GKCAPTCHA_SITE_KEY,
    secret: process.env.GKCAPTCHA_SECRET_KEY,
    token: req.body['gk-captcha-token'],
  }),
});
const result = await response.json();
// { success, score, timestamp, decision?, error?, reasonCode? }
// success only means the token is authentic. A "block" decision must be rejected.
if (result.success && result.decision !== 'block') {
  // Passed: process the form.
} else {
  // Failed or blocked: reject the request.
}

Next Steps