Getting Started

Captcha Service is a lightweight, self-hosted CAPTCHA API that generates challenge images and verifies user responses. It protects web forms and endpoints from automated bots without sending user data to third-party providers. Available as an open web service in Eyevinn Open Source Cloud.

Prerequisites

Step 1: Create a Captcha Service instance

Navigate to the Captcha Service page in the OSC web console and click Create captcha-svc. Fill in:

  • Name: a unique name for your instance (alphanumeric only, e.g. mycaptcha)

Click Create and wait for the status indicator to turn green.

Step 2: Generate a CAPTCHA challenge

Once the instance is running, note the service URL. To generate a challenge, call the /generate endpoint:

curl https://<instance-url>/generate

The response includes a challenge token and a base64-encoded image:

{
  "token": "abc123",
  "image": "data:image/png;base64,..."
}

Render the image in an <img> tag on your form and include the token as a hidden field.

Step 3: Verify a CAPTCHA response

When the user submits the form, call the /verify endpoint with the token and the text the user entered:

curl -X POST https://<instance-url>/verify \
  -H "Content-Type: application/json" \
  -d '{"token": "abc123", "answer": "XK9Q2"}'

A successful verification returns:

{ "valid": true }

An invalid answer or expired token returns { "valid": false }. Reject the form submission if valid is false.

Usage example

// Generate challenge (server-side)
const genRes = await fetch(`${captchaUrl}/generate`);
const { token, image } = await genRes.json();

// After form submission, verify on the server
const verifyRes = await fetch(`${captchaUrl}/verify`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ token, answer: req.body.captchaAnswer }),
});
const { valid } = await verifyRes.json();
if (!valid) throw new Error('CAPTCHA verification failed');

CLI usage

osc create birme-captcha-svc mycaptcha

Resources