Docs
Integrations
Javascript

Javascript

To use this integration you need to create an API key in your account.

Note

You can also use reCAPTCHA-compatible /siteverify endpoint directly (especially if you already have working reCAPTCHA integration) like in the tutorial example, this SDK is just Javascript-idiomatic implementation with convenience features.

This is a server-side SDK, which you would use to verify captcha solution against Private Captcha API. This SDK does not solve puzzles on the client side (used to protect APIs).

GitHub repository NPM package

Installation 

npm install private-captcha-js

Usage

Note

Before using this SDK, you’ll need an API key. If you don’t have one yet, see how to create it in the Getting Started guide.

Basic Verification

verify() supports automatic backoff and retrying (configured via VerifyInput parameter), enabled by default. You need to check the captcha verification status yourself.

import { createClient } from 'private-captcha-js';

const client = createClient({ apiKey: 'your-api-key' });

const result = await client.verify({ solution: 'captcha-solution-from-client' });
if (result.success) {
    console.log('Captcha verified!');
}

Express.js Middleware

middleware() returns a basic Express.js middleware that extracts and verifies form field, configured via Configuration object for the client instance.

import express from 'express';
import { createClient } from 'private-captcha-js';

const app = express();
app.use(express.urlencoded({ extended: true })); // Required

const client = createClient({ apiKey: 'your-api-key' });

// Protect route with middleware
app.post('/submit', client.middleware(), (req, res) => {
    res.send('Form submitted successfully!');
});

// Or verify manually
app.post('/verify', async (req, res) => {
    try {
        const result = await client.verifyRequest(req);
        res.json({ success: result.success });
    } catch (error) {
        res.status(403).json({ error: error.message });
    }
});

Configuration

Client configuration allows to set default form field, domain (can be used for self-hosting or EU isolation) and HTTP status for middleware version.

Client Options 

const client = createClient({
    apiKey: 'your-api-key',                 // Required
    formField: 'private-captcha-solution',  // Field from where to read the solution
    failedStatusCode: 403,                  // HTTP status code for failed verifications (middleware)
    domain: 'api.eu.privatecaptcha.com'        // Override for EU isolation or for self-hosting
});

Non-standard backend domains

For EU isolation, you can use the domain option:

const client = createClient({
    apiKey: 'your-api-key',
    domain: 'api.eu.privatecaptcha.com'  // EU domain
});

Retry Configuration

When verifying puzzle solutions, you can also specify some retry and backoff options.

client.verify({
    solution: 'solution',
    maxBackoffSeconds: 10,
    attempts: 10
});
Last updated on
PythonGo