Developer Documentation

import base64, urllib.request
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
from cryptography.exceptions import InvalidSignature

PUB_KEY_URL = "https://api.captxa.com/keys/Ed25519.txt"

def load_public_key():
    with urllib.request.urlopen(PUB_KEY_URL) as r:
        raw = base64.b64decode(r.read().strip())
    return Ed25519PublicKey.from_public_bytes(raw)

pub_key = load_public_key()  # call once at startup

def verify_captcha_token(token: str) -> bool:
    # token format: "SIMP|ts|ip|ja4|ja4o|<base64url_sig>"
    last_pipe = token.rfind("|")
    payload   = token[:last_pipe].encode()
    sig       = base64.urlsafe_b64decode(token[last_pipe+1:] + "==")
    try:
        pub_key.verify(sig, payload)
        return True
    except InvalidSignature:
        return False

// Requires libsodium (PHP 7.2+, enabled by default)
function loadPublicKey(): string {
    return base64_decode(trim(file_get_contents('https://api.captxa.com/keys/Ed25519.txt')));
}

$pubKey = loadPublicKey(); // cache in APCu at startup

function verifyCaptchaToken(string $token, string $pubKey): bool {
    // token format: "SIMP|ts|ip|ja4|ja4o|<base64url_sig>"
    $lastPipe = strrpos($token, '|');
    $payload  = substr($token, 0, $lastPipe);
    $sig      = base64_decode(strtr(substr($token, $lastPipe + 1), '-_', '+/'));
    return sodium_crypto_sign_verify_detached($sig, $payload, $pubKey);
}

import java.net.URI; import java.net.http.*;
import java.security.*; import java.security.spec.*;
import java.util.Base64;

public class CaptxaVerifier {
    private static final String PUB_URL = "https://api.captxa.com/keys/Ed25519.txt";
    private final PublicKey pubKey;

    public CaptxaVerifier() throws Exception {
        var client = HttpClient.newHttpClient();
        var req    = HttpRequest.newBuilder().uri(URI.create(PUB_URL)).build();
        byte[] raw = Base64.getDecoder().decode(
            client.send(req, HttpResponse.BodyHandlers.ofString()).body().trim());
        pubKey = KeyFactory.getInstance("Ed25519")
            .generatePublic(new X509EncodedKeySpec(addDerHeader(raw)));
    }

    public boolean verify(String token) throws Exception {
        // token format: "SIMP|ts|ip|ja4|ja4o|<base64url_sig>"
        int    lastPipe = token.lastIndexOf('|');
        byte[] payload  = token.substring(0, lastPipe).getBytes();
        byte[] sig      = Base64.getUrlDecoder().decode(token.substring(lastPipe + 1));
        Signature s = Signature.getInstance("Ed25519");
        s.initVerify(pubKey); s.update(payload);
        return s.verify(sig);
    }

    private byte[] addDerHeader(byte[] raw) {
        byte[] hdr = { 0x30,0x2a,0x30,0x05,0x06,0x03,0x2b,0x65,0x70,0x03,0x21,0x00 };
        byte[] out = new byte[hdr.length + raw.length];
        System.arraycopy(hdr,0,out,0,hdr.length);
        System.arraycopy(raw,0,out,hdr.length,raw.length);
        return out;
    }
}

import os, requests as http_client

def validate_captcha(token: str) -> dict:
    resp = http_client.post(
        "https://api.captxa.com/api/validate",
        json={
            "captcha_token": token,
            "api_token":    os.environ["CAPTXA_API_TOKEN"],
        },
        timeout=5,
    )
    if resp.status_code == 429:
        return {"valid": False, "reason": "request_limit"}
    data = resp.json()
    valid = data.get("Is_Correct") and not data.get("RequestLimit")
    return {"valid": valid, "requests": data.get("requests", 0)}

# Usage in a login route:
result = validate_captcha(request.form["captchatoken"])
if not result["valid"] or result["requests"] > 1:
    abort(403)

function validateCaptcha(string $token): array {
    $ch = curl_init('https://api.captxa.com/api/validate');
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
        CURLOPT_POSTFIELDS     => json_encode([
            'captcha_token' => $token,
            'api_token'     => getenv('CAPTXA_API_TOKEN'),
        ]),
    ]);
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($code === 429) return ['valid' => false];
    $data = json_decode($body, true);
    return [
        'valid'    => ($data['Is_Correct'] ?? false) && !($data['RequestLimit'] ?? false),
        'requests' => $data['requests'] ?? 0,
    ];
}

// Usage:
$result = validateCaptcha($_POST['captchatoken']);
if (!$result['valid'] || $result['requests'] > 1) { http_response_code(403); exit; }

import java.net.URI; import java.net.http.*;
import com.fasterxml.jackson.databind.ObjectMapper;

public record CaptchaResult(boolean valid, int requests) {}

public CaptchaResult validateCaptcha(String token) throws Exception {
    var body = "{\"captcha_token\":\"" + token +
               "\",\"api_token\":\"" + System.getenv("CAPTXA_API_TOKEN") + "\"}";
    var req = HttpRequest.newBuilder()
        .uri(URI.create("https://api.captxa.com/api/validate"))
        .POST(HttpRequest.BodyPublishers.ofString(body))
        .header("Content-Type", "application/json")
        .build();
    var res  = HttpClient.newHttpClient().send(req, HttpResponse.BodyHandlers.ofString());
    if (res.statusCode() == 429) return new CaptchaResult(false, 0);
    var json     = new ObjectMapper().readTree(res.body());
    boolean valid = json.path("Is_Correct").asBoolean()
                 && !json.path("RequestLimit").asBoolean();
    return new CaptchaResult(valid, json.path("requests").asInt());
}

// Usage in login handler:
var result = validateCaptcha(captchaToken);
if (!result.valid() || result.requests() > 1)
    throw new ResponseStatusException(HttpStatus.FORBIDDEN);