ENopenwaf.devPanel

Referencia de la API

Ver en Markdown

Gestiona zonas, registros DNS, ajustes de borde, reglas, analítica, agentes IA y egress con la API REST de OpenWAF.

En esta página

La API de OpenWAF es una API REST con JSON sobre HTTPS. Gestiona todo lo que hace el panel: zonas y registros DNS, ajustes de borde y reglas, certificados y caché, analítica, agentes IA, egress, miembros y tokens de API. Los SDK, la CLI y el servidor MCP usan esta misma API.

URL base

https://dash.openwaf.dev/v1

Los recursos de la organización están bajo /v1/orgs/{org} y los de una zona bajo /v1/orgs/{org}/zones/{zone}. {org} es el id de tu organización y {zone} el de una zona, ambos UUID. GET /v1/orgs devuelve la organización del token, y Listar zonas devuelve los ids de las zonas.

Autenticación

Cada petición lleva un token de API en la cabecera Authorization:

GET /v1/orgs HTTP/1.1
Host: dash.openwaf.dev
Authorization: Bearer owf_…

Los tokens se crean en el panel (Tokens de API) o con Crear un token. Un token actúa con un rol y se puede limitar a una zona o a un cliente. Una petición sobre una organización que no es la del token responde 404, igual que un recurso que no existe. Consulta Autenticación.

Peticiones y respuestas

  • Los cuerpos de las peticiones son JSON (Content-Type: application/json) salvo que la operación diga otra cosa, de hasta 1 MiB. Los campos desconocidos se rechazan con 400 bad_request.
  • Las fechas van en RFC 3339 y UTC, y los ids son UUID.
  • Las listas responden {"items": […]}. Las largas se paginan con limit y un cursor (cursor, before) que describe cada operación.
  • Las respuestas 204 No Content no llevan cuerpo.

Cambios de configuración

La configuración de una zona (registros, ajustes de borde, reglas, su cliente) está versionada: cada cambio crea una versión con su autor y su motivo, visible en Versiones de configuración y en la auditoría. Las escrituras que cambian la configuración admiten tres controles:

ControlDóndeEfecto
X-Change-ReasonCabeceraMotivo del cambio, de 1 a 500 caracteres, que queda en el historial y en la auditoría. Lo exigen la mayoría de las escrituras: sin él responden 422 reason_required.
dry_run=1ConsultaSimula el cambio: responde 200 con el plan (Applied), las diferencias y la versión que crearía. No guarda nada.
If-MatchCabeceraVersión actual esperada, p. ej. "12". Si la zona ha cambiado desde entonces, la escritura responde 412 version_conflict con current_version.

Las escrituras correctas devuelven la nueva versión en la cabecera X-Config-Version y en ETag (entre comillas, lista para If-Match). La forma segura de cambiar una zona, los mismos dos pasos que exige el servidor MCP:

  1. Envía la escritura con dry_run=1 y revisa el plan; la versión actual está en from_version (o en el ETag de la zona).
  2. Envía la misma escritura sin dry_run, con If-Match: "<versión>" y un X-Change-Reason. Si alguien ha cambiado la zona entretanto recibirás 412 version_conflict: vuelve a simular.

Errores

Los errores responden un estado HTTP y un cuerpo JSON con un code estable:

{"error": {"code": "invalid", "message": "ttl must be between 60 and 86400", "field": "ttl"}}

Todos los códigos están en Errores.

Límites de peticiones

Algunas operaciones tienen sus propios límites y, al superarlos, responden 429 con una cabecera Retry-After (en segundos):

OperaciónLímite
Purgar la cachéPor organización: 10 purgas por minuto con ráfagas de 30 (todo, nombres, prefijos, etiquetas) y 500 URL por minuto.
Escanear la preparación para agentesUna vez por nombre y minuto.
Stream de eventos de seguridad y stream de eventos de egress10 streams abiertos por organización.

Versiones de la API

Todas las rutas están bajo /v1. Con el tiempo, las respuestas pueden ganar campos nuevos y los enumerados valores nuevos: los clientes deben ignorar los campos que no conozcan. Los cambios de la API se anuncian en el registro de cambios.

SDK, CLI y MCP

SDKclientes de TypeScript y Python generados de esta API, un fichero cada uno.CLIopenwaf-cloud ctl, la API desde el terminal y desde scripts.Servidor MCPla API como herramientas para asistentes de IA, en https://mcp.openwaf.dev/mcp.

La propia API sirve los ficheros de los SDK sin autenticación: https://dash.openwaf.dev/v1/sdk/openwaf.ts y https://dash.openwaf.dev/v1/sdk/openwaf.py.

Referencia

OrganizacionesConsulta y renombra tu organización, la cuenta a la que pertenecen las zonas, los miembros y los tokens.Miembros e invitacionesLista, añade y quita a las personas de tu organización, cambia sus roles y gestiona las invitaciones.Tokens de APICrea, lista y revoca los tokens owf_ que autentican las peticiones a la API, la CLI y el servidor MCP.ClientesAgrupa las zonas por los clientes finales de una agencia y limita miembros y tokens a las zonas de un cliente.Marca blancaPon tu nombre, color y logotipo en el panel, sírvelo en tu propio dominio y usa tus propios servidores de nombres.AuditoríaLee la auditoría de tu organización, cada cambio hecho desde la API, el panel, la CLI o MCP.ZonasAñade, lista, comprueba y borra zonas (dominios), en modo DNS delegado o externo, y fusiona una zona en su padre.Versiones de configuraciónRecorre el historial de versiones de una zona, compara dos versiones, vuelve a una anterior y sigue su propagación al borde.Registros DNSLista, crea, modifica y borra los registros DNS de una zona, en bloque o en un lote, e importa los registros existentes.DNS del correoPlanifica los registros MX, SPF, DKIM y DMARC de tus proveedores de correo y comprueba los registros de correo de una zona.Ajustes de bordeConsulta y cambia los ajustes de borde de una zona (WAF, origen, TLS, caché, agentes IA…) y la configuración efectiva de un nombre.ReglasAñade, lista y borra las reglas de borde de una zona, reglas de IP y país, excepciones del WAF y límites de peticiones.CachéPurga lo que el borde guardó en caché de una zona, todo o por URL, prefijo, nombre o etiqueta, y sigue las purgas recientes.Certificados del bordeLista los certificados TLS de una zona y el estado del certificado de cada sitio con proxy.TLS al origen y Origin CAEmite y revoca certificados de origen de la OpenWAF Origin CA, comprueba el TLS al origen y descarga las CA.Eventos de seguridadConsulta los eventos de seguridad de una zona, con filtros, resúmenes, histogramas y un stream en directo (Server-Sent Events).UsoContadores diarios de tráfico de una zona en el borde, peticiones, peticiones bloqueadas, bytes y consultas DNS.Rendimiento real (RUM)Core Web Vitals medidos en los navegadores de tus visitantes, LCP, INP, CLS, FCP y TTFB, por página, país, dispositivo y más.Agentes IACómo usan una zona los rastreadores y agentes IA, por categoría, bot y operador, más trampas, señales, MCP Shield y el catálogo.Preparación para agentesEscanea lo preparado que está un nombre de la zona para agentes IA, reglas de robots.txt, sitemap, llms.txt, markdown y datos estructurados.EgressGestiona OpenWAF Egress, la pasarela entre tus agentes IA y sus proveedores, con destinos, credenciales, agentes y eventos.
  • Esquemas: todos los objetos que devuelve o acepta la API.

Sesión del panel

La entrada (/v1/auth/…), la aceptación de invitaciones y el borrado de la cuenta sirven al panel con una cookie de sesión y no forman parte de la API con tokens. Con la cookie de sesión, el panel también llama a las rutas de esta referencia; sus escrituras exigen entonces la cabecera X-CSRF-Token. Las integraciones usan siempre un token de API.

Última actualización:

↑↓ para moverte↵ para abriresc para cerrar