Referencia de la API REST de Zeuslock

URL base y alojamiento

Todos los endpoints REST de Zeuslock comparten una única URL base:

https://api.zeuslock.ai/v1

La API multi-tenant compartida se aloja en eu-west-3 (París). Los datos de cliente, los registros de incidentes y la configuración nunca salen de la Unión Europea. Si utiliza la edición soberana, su URL base es un subdominio dedicado — típicamente https://api.<tenant>.zeuslock.cloud/v1 — con exactamente los mismos endpoints, payloads y comportamiento. Cambia el host y todo lo demás es idéntico.

La API solo habla JSON sobre HTTPS. Las solicitudes en texto plano se rechazan en el edge. Todas las conexiones terminan en TLS 1.3 con Perfect Forward Secrecy.

Autenticación

Hay dos métodos disponibles. Elija uno por integración; no los mezcle en la misma solicitud.

Clave de API (servidor a servidor)

Las claves de API son el método por defecto para automatización backend, integraciones SIEM, pipelines CI/CD y scripts. Cree una en la consola del operador, en Configuración → Claves API, y pásela como bearer token:

curl -H "Authorization: Bearer zlsk_live_8f3c..." \
     https://api.zeuslock.ai/v1/incidents

Las claves llevan el prefijo zlsk_live_ o zlsk_test_ para distinguir entornos de un vistazo. Cada clave tiene un alcance explícito:

• read-only — GET sobre incidentes, políticas y detectores.
• incidents-write — actualiza el estado y añade comentarios a incidentes.
• admin — crea o modifica detectores, políticas y webhooks.

Las claves se muestran una sola vez al crearlas. Rótelas desde la consola; la revocación es efectiva en menos de cinco segundos en todas las regiones.

OAuth 2.0 (en nombre del usuario)

Para integraciones de interfaz que actúan en nombre de un operador conectado, utilice el flujo estándar authorization code con PKCE. El endpoint de autorización es https://app.zeuslock.ai/oauth/authorize y el de token https://api.zeuslock.ai/v1/oauth/token. Los scopes son equivalentes a los de las claves de API. Los access tokens duran una hora y los refresh tokens rotan en cada uso.

Límites de tasa

Cada clave de API tiene derecho a 60 solicitudes por segundo sostenidas y un pico de 600 req/s. El bucket se recarga al ritmo sostenido. Cada respuesta lleva tres cabeceras para que su cliente se autorregule:

• X-RateLimit-Limit — tope sostenido para esta clave.
• X-RateLimit-Remaining — solicitudes restantes en la ventana actual.
• X-RateLimit-Reset — segundos epoch en los que se reinicia la ventana.

Cuando el bucket se agota, la API devuelve 429 Too Many Requests con una cabecera Retry-After en segundos. Aplique back-off exponencial; no reintente nunca antes del valor indicado.

Visión general de los endpoints

Incidentes

Listar incidentes

Devuelve los incidentes en orden cronológico inverso con paginación por cursor. El campo next_cursor, cuando aparece, es opaco: páselo tal cual en la siguiente llamada.

curl -H "Authorization: Bearer zlsk_live_8f3c..." \
     "https://api.zeuslock.ai/v1/incidents?since=2026-05-01T00:00:00Z&severity=high&limit=100"

import httpx

client = httpx.Client(
    base_url="https://api.zeuslock.ai/v1",
    headers={"Authorization": "Bearer zlsk_live_8f3c..."},
    timeout=30,
)

params = {"since": "2026-05-01T00:00:00Z", "severity": "high", "limit": 100}
while True:
    resp = client.get("/incidents", params=params)
    resp.raise_for_status()
    page = resp.json()
    for incident in page["items"]:
        print(incident["id"], incident["detector"], incident["severity"])
    if not page.get("next_cursor"):
        break
    params["cursor"] = page["next_cursor"]

import fetch from "node-fetch";

const base = "https://api.zeuslock.ai/v1";
const headers = { Authorization: "Bearer zlsk_live_8f3c..." };

let cursor;
do {
  const url = new URL(`${base}/incidents`);
  url.searchParams.set("since", "2026-05-01T00:00:00Z");
  url.searchParams.set("severity", "high");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);

  const res = await fetch(url, { headers });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const page = await res.json();
  for (const i of page.items) console.log(i.id, i.detector, i.severity);
  cursor = page.next_cursor;
} while (cursor);

Obtener un incidente

GET /v1/incidents/{id} devuelve el incidente completo, incluido el contexto del prompt. Las coincidencias sensibles se devuelven redactadas por defecto (por ejemplo sk-***), con los offsets para que pueda reconstruir la visualización en su herramienta.

Actualizar el estado del incidente

Haga avanzar un incidente por su flujo de triaje. Valores válidos: open, in_review, resolved y false_positive. La transición a false_positive alimenta el job de calibración de detectores que se ejecuta cada noche.

curl -X POST "https://api.zeuslock.ai/v1/incidents/inc_8c1f.../status" \
     -H "Authorization: Bearer zlsk_live_8f3c..." \
     -H "Content-Type: application/json" \
     -d '{"status":"resolved","comment":"Clave de prueba confirmada, rotación realizada."}'

Políticas

GET /v1/policies lista todas las políticas activas, con el modo (monitor, anonymize o block) por tipo de finding y los grupos de usuarios a los que aplica.

PUT /v1/policies/{id} actualiza una política. Añada ?dry_run=true para validar el cambio contra los últimos siete días de tráfico sin aplicarlo realmente — la respuesta contiene el diff de los incidentes que se habrían creado, anonimizado o bloqueado. Es la forma recomendada de pasar de Monitor a Block.

resp = client.put(
    "/policies/pol_credentials",
    params={"dry_run": "true"},
    json={"findings": {"api_key": {"mode": "block"}}},
)
resp.raise_for_status()
print(resp.json()["dry_run_summary"])  # {"would_block": 12, "would_warn": 0, ...}

Detectores

Los detectores personalizados capturan identificadores específicos de su organización: códigos de empleado internos, números de referencia de cliente, formatos de token propietarios. GET /v1/detectors los lista; POST /v1/detectors crea uno. Cada detector combina una regex con uno o varios post-validadores para mantener una precisión alta:

• luhn — checksum tipo tarjeta bancaria.
• mod97 — checksum tipo IBAN.
• entropy_gt — rechaza coincidencias cuya entropía de Shannon esté por debajo de un umbral (típicamente 4.5) para evitar cadenas de ejemplo.

const body = {
  name: "id_cliente_interno",
  regex: "\\bCUST-[A-Z0-9]{10}\\b",
  post_validators: [{ type: "entropy_gt", value: 4.5 }],
  severity: "medium",
  action: "anonymize"
};

const res = await fetch(`${base}/detectors`, {
  method: "POST",
  headers: { ...headers, "Content-Type": "application/json" },
  body: JSON.stringify(body)
});
console.log(await res.json());

Análisis síncrono

POST /v1/scan es el caballo de batalla para jobs de CI/CD y tareas batch. Envíe texto en bruto y reciba los findings en un único viaje de ida y vuelta. Las solicitudes están limitadas a 1 MB por llamada con un timeout de 30 segundos; para payloads mayores, divida en cliente o use el endpoint batch asíncrono (cubierto en un doc aparte).

curl -X POST "https://api.zeuslock.ai/v1/scan" \
     -H "Authorization: Bearer zlsk_live_8f3c..." \
     -H "Content-Type: application/json" \
     -d '{"text":"Conectar con AKIAIOSFODNN7EXAMPLE y contraseña hunter2","detectors":["api_key","password"]}'

payload = {"text": open("build.log").read(), "detectors": ["api_key", "private_key", "jwt"]}
findings = client.post("/scan", json=payload).json()["findings"]
if findings:
    raise SystemExit(f"Build fallido: {len(findings)} secretos detectados")

Errores

Todas las respuestas de error usan el mismo sobre JSON para facilitar logging y enrutado:

{
  "error": {
    "code": "invalid_scope",
    "message": "Esta clave de API es de solo lectura y no puede modificar políticas.",
    "request_id": "req_01HX9YJ3K4M5N6P7Q8R9S0T1U2"
  }
}

Cite siempre request_id al contactar con soporte. Códigos HTTP habituales:

• 400 Bad Request — JSON malformado o campo requerido ausente.
• 401 Unauthorized — bearer token ausente o inválido.
• 403 Forbidden — token válido pero scope insuficiente.
• 404 Not Found — recurso desconocido o fuera de su tenant.
• 422 Unprocessable Entity — estructura válida pero valores inválidos (regex incorrecta, transición de estado prohibida).
• 429 Too Many Requests — respete Retry-After.
• 500 Internal Server Error — reintento seguro con back-off exponencial.

Webhooks

Para entrega push de incidentes a Slack, Splunk HEC, PagerDuty o Microsoft Sentinel, configure un webhook en la consola del operador. Consulte el doc de Webhooks para el esquema de payload y la verificación de firma HMAC.