Operación

Comportamiento ante caídas, rotación de claves, ejemplos de servidor, dominios y política de seguridad de contenidos.

En esta página

Gestión de errores y fail-open Claves y rotación Ejemplos de backend Dominios, CORS y CSP

Gestión de errores y fail-open

Si el servicio de CaptchaCore no está disponible, el comportamiento se puede configurar:

Fail-Open (estándar)

Los formularios se dejan pasar de todos modos. Disponibilidad > seguridad en caso de fallo. Recomendado para la mayoría de los sitios.

CAPTCHACORE_FAIL_OPEN=true

Fail-Closed

Los formularios se bloquean si el servicio no responde. Solo para sistemas altamente críticos.

CAPTCHACORE_FAIL_OPEN=false

Todas las llamadas a la API tienen un timeout de 3 segundos. Si se supera, se aplica la configuración fail-open/closed.

Claves y rotación

Cada sitio tiene un par de claves: Site Key (pública, en el navegador) y Secret Key (secreta, solo en el servidor).

Formatos de claves

cc_pub_6e65b5c4597a688c93f3be6e345ee1a5...  ← 7 + 64 hex = 71 Zeichen
cc_sec_8bb043aa6424a1fdb3e048d2d3232894...  ← 7 + 64 hex = 71 Zeichen

Rotación de claves

Al rotar, la clave anterior pasa al estado rotated y sigue siendo válida durante 24 horas. Así se pueden realizar rolling deployments sin downtime.

active — clave actual, se usa para las nuevas peticiones
rotated — clave anterior, válida aún 24h (configurable)
revoked — invalidez inmediata, ya no son posibles más peticiones

Seguridad de la secret key

  • La secret key se almacena en la base de datos como hash SHA-256
  • El texto claro se muestra solo una vez tras la creación
  • No se puede recuperar — en caso de pérdida: generar una clave nueva
  • Nunca se muestra en logs, respuestas de la API ni mensajes de error

Ejemplos de backend

El endpoint de verify puede llamarse desde cualquier backend. Aquí tienes ejemplos en los lenguajes más habituales:

PHP (sin framework)

$token = $_POST['captchacore_token'] ?? '';

$ch = curl_init('https://api.captchacore.eu/api/v2/verify');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 3,
    CURLOPT_HTTPHEADER     => [
        'X-CaptchaCore-Key: cc_sec_DEIN_SECRET',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'token'     => $token,
        'form_type' => 'contact',
    ]),
]);
$result = json_decode(curl_exec($ch), true);

if (!$result['valid']) {
    die('Bot erkannt.');
}

Node.js

const token = req.body.captchacore_token;

const res = await fetch('https://api.captchacore.eu/api/v2/verify', {
  method: 'POST',
  headers: {
    'X-CaptchaCore-Key': process.env.CAPTCHACORE_SECRET_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ token, form_type: 'register' }),
});
const { valid, risk_score, action } = await res.json();

if (!valid) return res.status(403).json({ error: 'Bot detected' });

Python

import requests

result = requests.post(
    'https://api.captchacore.eu/api/v2/verify',
    headers={'X-CaptchaCore-Key': 'cc_sec_DEIN_SECRET'},
    json={'token': token, 'form_type': 'login'},
    timeout=3,
).json()

if not result['valid']:
    raise Exception('CaptchaCore verification failed')

Infraestructura y dominios

Arquitectura de dominios

Dominio Finalidad Tipo
api.captchacore.euChallenge, Verify, Status, VersionAPI (JSON)
src-eu.captchacore.euJS del widget + worker (CDN solo UE)CDN (estándar)
src.captchacore.euJS del widget + worker (CDN global)CDN (opcional)
captchacore.euSitio web, panel de administración, docsFrontend

Content Security Policy (CSP)

Si utiliza una Content Security Policy en su sitio web, deben permitirse los siguientes dominios:

# Minimal (EU-only CDN + API)
script-src  https://src-eu.captchacore.eu;
connect-src https://api.captchacore.eu https://src-eu.captchacore.eu;
worker-src  blob:;

# Mit globalem CDN (zusätzlich)
script-src  https://src.captchacore.eu;
connect-src https://src.captchacore.eu;

¿Por qué estas entradas?

  • script-src — El JS del widget (captchacore-v2.min.js) se carga desde el CDN
  • connect-src (API) — El widget llama a /api/v2/challenge mediante fetch()
  • connect-src (CDN) — El worker de PoW se carga desde el CDN mediante fetch()
  • worker-src blob: — El worker se instancia como URL de blob (evita CORS)

Cabeceras CORS

CaptchaCore establece automáticamente las cabeceras CORS correctas en todos los endpoints de la API. Usted no necesita realizar ninguna configuración CORS por su parte. La API responde con:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Accept, X-CaptchaCore-Key

Ejemplo de NGINX para su sitio web

Si ha configurado una CSP estricta en su sitio web:

# NGINX — CSP für CaptchaCore Widget
add_header Content-Security-Policy
  "script-src 'self' https://src-eu.captchacore.eu;
   connect-src 'self' https://api.captchacore.eu https://src-eu.captchacore.eu;
   worker-src 'self' blob:;"

Atrás

Detección

Siguiente

Ayuda y privacidad