API de lectura

Autenticación

Cada petición lleva la clave de la organización en la cabecera Authorization, como Bearer.

Authorization: Bearer alx_live_…

La clave empieza por alx_live_. Sus primeros 17 caracteres son el prefijo que ves en Ajustes → API. La clave completa se muestra una sola vez, al crearla: Alethexis guarda solo su huella SHA-256 y no puede volver a enseñártela.

Una clave revocada deja de funcionar en la petición siguiente.

Una clave ausente, desconocida, incorrecta o revocada recibe la misma respuesta 401: la API no distingue entre esos casos.

Cuota

Cada clave admite 120 peticiones por minuto y 10.000 al día.

Toda respuesta autenticada lleva X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Al agotarse la cuota, la respuesta es 429 con Retry-After, en segundos.

Además, cada dirección IP admite 60 peticiones cada 10 segundos. Por encima, la petición se bloquea durante 10 segundos.

Paginación

Los listados devuelven un objeto con data y next_cursor.

limit va de 1 a 200; si no se indica, 50.

Para la página siguiente, repite la petición con cursor igual al next_cursor recibido. En la última página, next_cursor es null.

El cursor es opaco: no lo construyas ni lo modifiques.

Errores

Todos los errores tienen la misma forma: un objeto error con code y message. El message está en inglés técnico; el code es estable.

Recursos

Todos admiten limit, cursor y since (fecha ISO 8601 con zona horaria).

Qué no devuelve la API

La API no devuelve datos de personas ni textos escritos a mano. Por recurso, queda fuera:

• systems: quién creó o editó el sistema, la persona indicada en la verificación de prácticas prohibidas, la finalidad y las notas.
• classifications: quién clasificó y la justificación escrita.
• controls: el responsable y el aprobador asignados, las notas y los enlaces a ficheros de evidencia.
• evidence: el fichero, su ruta de almacenamiento, el título, la descripción y quién lo subió.
• sections: el motivo de revisión y sus detalles.
• approvals: quién registró el acto, sus roles y el comentario.
• audit-log: quién actuó, la dirección IP, el navegador y los valores anteriores y posteriores al cambio.
• requests: quién la pidió, la revisó o la decidió, la finalidad, los usuarios previstos, las notas sobre datos personales, el comentario de la decisión y los comentarios.

Webhooks

Un webhook avisa a tu sistema en cuanto pasa algo, sin que tengas que consultar la API. Los registra el Owner en Ajustes → Webhooks: una URL https, los eventos que quieres y un secreto que se muestra una sola vez.

{
  "id": "0f3a…",                 // Alethexis-Event-Id
  "type": "section.closed",
  "created_at": "2026-09-18T09:12:03.412Z",
  "api_version": "v1",
  "data": { "account_id": "…", "section_id": "GOB-2", "status": "complete", "closed_at": "…" }
}

// Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';

export function verify(rawBody, header, secret, toleranceSeconds = 300) {
  const [t, v1] = header.split(',').map((part) => part.split('=')[1]);
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;

  const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
  const received = Buffer.from(v1, 'hex');
  return expected.length === received.length && timingSafeEqual(expected, received);
}

# Python
import hashlib, hmac, time

def verify(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > tolerance:
        return False

    expected = hmac.new(
        secret.encode(), f'{parts["t"]}.'.encode() + raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Versiones

v1 es un contrato: sus respuestas no cambian de forma incompatible. Un cambio incompatible se publica como una versión nueva, v2.

Especificación OpenAPI

La especificación OpenAPI 3.1 se genera desde los mismos esquemas que validan cada respuesta: /api/v1/openapi.json

Ejemplo

curl -H "Authorization: Bearer $ALETHEXIS_API_KEY" \
  "https://www.alethexis.com/api/v1/systems?limit=50"