API pública (token por usuario)
Objetivo
Sección titulada «Objetivo»Automatizar la plataforma fuera del panel: un script o un agent hace las mismas acciones que usted haría en pantalla, usando un token de API. El token es la puerta de entrada a la misma lógica del panel, así que pasa por los mismos controles: el cliente al que pertenece, su rol (Gerente, Editor o Visualizador), los módulos contratados y, por encima de todo eso, el alcance del token (solo lectura o lectura y escritura). El token nunca da más acceso del que usted tiene; si su rol cambia o usted sale del cliente, el token pierde el acceso también.
Quién puede: cualquier persona del cliente genera y administra sus propios tokens. Lo que el token hace está limitado por su rol y por el alcance elegido.
Las tres garantías
Sección titulada «Las tres garantías»- Un solo cliente. El token vale para el cliente en que fue generado y para ningún otro, en ninguna circunstancia. El servidor lee el cliente del propio token; ninguna ruta de la API acepta un identificador de cliente por ruta, parámetro, cuerpo o encabezado. Todo acceso a datos corre aislado por cliente en la base (RLS). Un
idde otro cliente responde404, como si no existiera. - El alcance es un techo, no un añadido. Un token de solo lectura solo hace
GET; cualquierPOST,PUToDELETEresponde403antes de llegar a la acción. Un token de lectura y escritura sigue limitado por el rol actual de quien lo generó, verificado en cada llamada: un Visualizador no puede generar un token de escritura, y un token de escritura de alguien que pasó a Visualizador pasa a solo leer. - Ningún secreto en claro. El valor del token aparece una sola vez; en la base queda solo un hash. La lista, la auditoría y los logs muestran solo el identificador público.
Equipo V2 (administradores de la plataforma): el token de un administrador actúa como administrador dentro del cliente en que fue generado (rol
admin, nivel total en todos los módulos de ese cliente), y sigue atado a ese cliente. Trátelo como una credencial administrativa: validez corta, uno por integración, y revóquelo al terminar.
Generar un token
Sección titulada «Generar un token»- En el menú, abra Gestión de la cuenta y haga clic en Tokens de API.
- Dele un nombre (por ejemplo,
script de backupoagent de DNS). - Elija el alcance: Solo lectura (GET) o Lectura y escritura. Prefiera solo lectura; escritura solo cuando la integración necesite crear, modificar o eliminar. Si su rol solo permite ver, la opción de escritura aparece deshabilitada (y el servidor la rechaza con
403aunque alguien fuerce el pedido). - Elija la validez: 30 días, 90 días (recomendado y predeterminado), 1 año o sin expiración. Un token expirado responde
401. - Haga clic en Generar token. El valor completo aparece una sola vez — empieza con
v2dns_. Cópielo y guárdelo en un lugar seguro (una bóveda de secretos). No se mostrará de nuevo.
En la base guardamos solo un hash del secreto; ni Version2 puede recuperar el valor. Si pierde el token, revóquelo (o rótelo) y use el nuevo.
Límites: hasta 20 tokens activos por persona y hasta 10 generaciones por hora.
Revocar
Sección titulada «Revocar»En la misma pantalla, la lista muestra sus tokens con el identificador público (el tramo v2dns_<identificador>, sin el secreto), el alcance, cuándo se creó, el último uso, la validez y el estado. Haga clic en Revocar para desactivar un token al instante — las integraciones que lo usan dejan de funcionar de inmediato. La fila sigue en la lista (y en la auditoría) marcada como revocada.
Haga clic en Rotar para cambiar el secreto sin recrear la configuración: se genera un token nuevo con el mismo nombre, alcance y validez restante, y el antiguo se revoca en la misma operación. El valor nuevo aparece una vez; cámbielo en su integración de inmediato. Rote periódicamente (por ejemplo, cada 90 días) y siempre que sospeche una filtración.
Revocación automática
Sección titulada «Revocación automática»Todos sus tokens se revocan automáticamente cuando su credencial cambia de manos: cambio de contraseña, restablecimiento de contraseña por “Olvidé mi contraseña”, recuperación o restablecimiento del verificador en dos pasos. Es intencional: una cuenta recuperada no puede quedarse con un token que alguien haya generado durante un acceso indebido. Después de recuperar la cuenta, genere tokens nuevos.
Autenticación
Sección titulada «Autenticación»Envíe el token en el encabezado Authorization, con el esquema Bearer:
Authorization: Bearer v2dns_a1b2c3d4e5f6a7b8_SECRETO...- Toda ruta de la API exige un token válido. Sin token, o con token inválido, revocado o expirado:
401con el encabezadoWWW-Authenticate: Bearer realm="v2dns"(la respuesta es genérica y no revela si el token existe). - La API no usa cookies ni la sesión del navegador, así que CSRF no aplica. Por eso es para integración server-to-server y agents, no para el navegador de terceros: no hay CORS habilitado.
- El token de la API no vale en la API interna del panel (
/api/v1/...), y la cookie del panel no vale en la API pública. - Las solicitudes con cuerpo (POST, PUT) necesitan
Content-Type: application/json.
Base y versionado
Sección titulada «Base y versionado»Todas las rutas están bajo un prefijo con versión:
https://dns.version2.network/api/pub/v1La versión en la ruta (v1) solo cambia en alteraciones incompatibles. Pueden agregarse campos nuevos a una respuesta sin cambiar la versión, así que su integración debe ignorar campos que no conoce.
Formato de respuestas y errores
Sección titulada «Formato de respuestas y errores»Las respuestas son JSON (Content-Type: application/json), salvo los endpoints .csv y el contenido de backup, que son texto. Los campos desconocidos en el cuerpo de una solicitud se rechazan con 400 (evita errores silenciosos por un campo mal escrito). El cuerpo de una solicitud puede tener hasta 2 MiB; cada solicitud tiene 60 s para terminar.
Los errores siguen siempre el mismo formato:
{ "error": "mensaje legible", "fields": [ { "field": "nombre_del_campo", "message": "qué corregir" } ] }| Código | Cuándo |
|---|---|
400 |
Cuerpo inválido, campo faltante, campo desconocido, cuerpo demasiado grande |
401 |
Token ausente, inválido, revocado o expirado (con WWW-Authenticate) |
403 |
Token de solo lectura en POST/PUT/DELETE; el rol no permite la acción; módulo no habilitado para el cliente |
404 |
Recurso no encontrado (o de otro cliente, o sin permiso para verlo) |
409 |
Conflicto (por ejemplo, editar una lista que no está en borrador, nombre repetido, backup ya en curso) |
415 |
Faltó Content-Type: application/json |
422 |
La acción se intentó y falló del lado del equipo (por ejemplo, backup manual) |
429 |
Límite de solicitudes alcanzado |
500 |
Error interno (sin detalles internos en la respuesta) |
Límites de uso
Sección titulada «Límites de uso»- Por token: hasta 120 solicitudes por minuto (cuenta solo para llamadas con el secreto correcto: alguien que conozca solo el identificador público no puede bloquear su token).
- Por IP: hasta 300 solicitudes por minuto.
Por encima de eso, la API responde 429; espere y reintente.
Auditoría
Sección titulada «Auditoría»Toda escritura (POST, PUT, DELETE) queda en la auditoría del cliente con quién la hizo, qué token (identificador público) y qué ruta:
api.escrita— la acción se ejecutó (estado2xx); el detalle de lo que cambió está en el evento del propio recurso (por ejemplo,acesso.equipamento_criado).api.escrita_negada— la acción fue rechazada (alcance de solo lectura, rol insuficiente o error de validación), con el estado devuelto.
La generación, la rotación y la revocación de tokens también quedan en la auditoría (conta.api_token_criado, conta.api_token_girado, conta.api_token_revogado).
Niveles por módulo
Sección titulada «Niveles por módulo»Cada módulo tiene un nivel: 0 ninguno, 1 ver, 2 escribir, 3 total. El rol predeterminado vale igual en todos los módulos: Visualizador = 1, Editor = 2, Gerente = 3. Los permisos de abajo citan el nivel mínimo exigido; recuerde que un token de solo lectura solo hace GET, cualquiera sea el nivel.
Endpoints
Sección titulada «Endpoints»Las rutas son relativas a la base https://dns.version2.network/api/pub/v1. En los ejemplos, $V2_TOKEN es su token.
| Módulo | Método y ruta | Permiso |
|---|---|---|
| — | GET /health |
ninguno |
| Cuenta | GET /whoami |
token válido |
| Cuenta | GET /audit |
conta: total (3) |
| Acceso Remoto | GET /hosts, GET /hosts/{id} |
acesso: ver (1) |
| Acceso Remoto | POST /hosts, PUT /hosts/{id}, DELETE /hosts/{id} |
escritura + gestión del inventario |
| Acceso Remoto | GET /sessions |
acesso: ver (1) |
| Backup | GET /backup/summary |
backup: ver (1) |
| Backup | GET /hosts/{id}/backups |
backup: ver (1) |
| Backup | GET /backups/{id} |
backup: total (3) o gestión del Acceso Remoto |
| Backup | POST /hosts/{id}/backup |
escritura + backup: total (3) |
| DNS | GET /dns/blocks, GET /dns/blocks/{id}, GET /dns/blocks/{id}/domains.csv |
dns: ver (1) |
| DNS | POST /dns/blocks, PUT /dns/blocks/{id}, DELETE /dns/blocks/{id} |
escritura + dns: escribir (2) |
| DNS | GET /dns/overview, GET /dns/stats, GET /dns/incidents, GET /dns/incidents/{id} |
dns: ver (1) |
| DNS | GET /dns/groups, GET /dns/groups/{id}, GET /dns/nodes, GET /dns/nodes/{id}, GET /dns/nodes/{id}/metrics |
dns: ver (1) |
| DNS | GET /dns/approvals, GET /dns/approvals/{id} |
dns: ver (1) |
| RPKI | GET /rpki, GET /rpki/cas/{id}/roas, GET /rpki/routers |
rpki: ver (1) |
GET /health
Sección titulada «GET /health»Verifica si la API está en línea. Único endpoint sin token. No trae datos del cliente.
curl https://dns.version2.network/api/pub/v1/health{ "status": "ok" }GET /whoami
Sección titulada «GET /whoami»Muestra el cliente fijo del token, el alcance, su rol y los niveles por módulo. Útil para que la integración confirme qué puede hacer.
curl -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/whoami{ "tenant": { "id": "3f2a...", "name": "Proveedor Ejemplo" }, "role": "gerente", "levels": { "dns": 3, "rpki": 3, "acesso": 3, "backup": 3, "conta": 3 }, "modulos": ["dns", "rpki", "acesso", "backup"], "token": "a1b2c3d4e5f6a7b8", "scope": "escrita"}GET /audit
Sección titulada «GET /audit»El registro de auditoría del cliente (hasta los 300 eventos más recientes). Solo para quien tiene total en Gestión de la cuenta.
| Parámetro | Observación |
|---|---|
q |
texto a buscar (acción, objetivo, persona) |
modulo |
dns, rpki, acesso, backup o conta |
from, to |
fechas AAAA-MM-DD |
curl -H "Authorization: Bearer $V2_TOKEN" \ "https://dns.version2.network/api/pub/v1/audit?modulo=acesso&from=2026-11-01"[ { "at": "2026-11-04T18:20:00Z", "actor": "Ana", "action": "api.escrita", "target": "POST /api/pub/v1/hosts", "ip": "198.51.100.5", "data": { "token": "a1b2c3d4e5f6a7b8", "status": 201 }, "modulo": "conta" }]Equipos (Acceso Remoto)
Sección titulada «Equipos (Acceso Remoto)»Los equipos del módulo Acceso Remoto (inventario compartido con Backup). Las contraseñas de las credenciales nunca vuelven en la lectura.
GET /hosts
Sección titulada «GET /hosts»Lista los equipos, grupos y proxies del cliente.
| Permiso | acesso: ver (1) |
curl -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/hosts{ "grupos": [ { "id": "9a1b...", "path": "Matriz / Borde" } ], "proxies": [ { "id": "5c7d...", "name": "Conector Matriz", "online": true } ], "equipamentos": [ { "id": "b2e4...", "name": "BORDE-01", "address": "198.51.100.10", "kind": "roteador", "vendor": "mikrotik", "ssh_port": 22, "telnet_port": null, "winbox_port": 8291, "rdp_port": null, "tags": ["borde"], "grupos": ["9a1b..."], "proxy": "Conector Matriz", "cred_mode": "salva", "cred_user": "v2adm", "has_secret": true, "backup": false } ], "idle_minutes": 5, "pode_gerir": true, "pode_backup": true}GET /hosts/{id}
Sección titulada «GET /hosts/{id}»Detalles de un equipo.
| Permiso | acesso: ver (1) — solo lo ve quien alguna regla habilita; quien gestiona ve todo |
| Parámetros | id (ruta) — id del equipo |
curl -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/hosts/b2e4...{ "id": "b2e4...", "name": "BORDE-01", "address": "198.51.100.10", "kind": "roteador", "vendor": "mikrotik", "cred_mode": "salva", "cred_user": "v2adm", "mfa": false, "ssh": true, "telnet": false, "winbox": true, "rdp": false, "proxy": "Conector Matriz", "idle_minutes": 5}Errores: 404 si el equipo no existe (o es de otro cliente, o ninguna regla lo habilita para usted).
POST /hosts
Sección titulada «POST /hosts»Crea un equipo.
| Permiso | token de escritura + Total en Acceso Remoto o en Backup (quien gestiona el inventario) |
Cuerpo:
| Campo | Tipo | Observación |
|---|---|---|
name |
string | obligatorio, hasta 64 caracteres |
address |
string | IP del equipo (IPv4 o IPv6), sin máscara |
kind |
string | servidor, roteador o switch (predeterminado roteador) |
vendor |
string | linux/windows (servidor) o mikrotik/cisco/juniper/huawei/outro |
ssh_port |
número o null | informe el puerto de al menos un protocolo |
telnet_port |
número o null | |
winbox_port |
número o null | solo MikroTik |
rdp_port |
número o null | solo servidor Windows |
tags |
string[] | hasta 32 etiquetas |
grupos |
string[] | ids de grupos a los que pertenece el equipo |
proxy_id |
string o null | proxy elegido (null: hereda del grupo o el predeterminado) |
cred_mode |
string | salva (guarda la credencial) o digitada (la pide en cada acceso) |
cred_user |
string | usuario, cuando cred_mode = salva |
cred_password |
string | contraseña, cuando cred_mode = salva |
backup |
boolean | activa el backup de configuración (exige SSH y credencial guardada, o backup_user) |
backup_user, backup_password |
string | credencial propia del backup (opcional) |
curl -X POST -H "Authorization: Bearer $V2_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"BORDE-01","address":"198.51.100.10","kind":"roteador","vendor":"mikrotik","ssh_port":22,"cred_mode":"digitada","grupos":[]}' \ https://dns.version2.network/api/pub/v1/hostsRespuesta 201:
{ "id": "b2e4..." }Errores: 400 (campos inválidos, con fields), 403 (token de solo lectura o sin permiso de gestión), 409 (nombre repetido), 404 (grupo o proxy inexistente).
PUT /hosts/{id}
Sección titulada «PUT /hosts/{id}»Edita un equipo. Mismo cuerpo del POST. Deje cred_password fuera para mantener la contraseña guardada.
| Permiso | token de escritura + Total en Acceso Remoto o en Backup |
| Parámetros | id (ruta) |
curl -X PUT -H "Authorization: Bearer $V2_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"BORDE-01-RJ","address":"198.51.100.10","kind":"roteador","vendor":"mikrotik","ssh_port":22,"cred_mode":"digitada","grupos":[]}' \ https://dns.version2.network/api/pub/v1/hosts/b2e4...Respuesta 200: { "id": "b2e4..." }. Error 404 si el id no es de este cliente.
DELETE /hosts/{id}
Sección titulada «DELETE /hosts/{id}»Elimina un equipo (y su historial de backup).
| Permiso | token de escritura + Total en Acceso Remoto o en Backup |
| Parámetros | id (ruta) |
curl -X DELETE -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/hosts/b2e4...Respuesta 200: { "message": "Equipamento BORDE-01-RJ removido." }.
GET /sessions
Sección titulada «GET /sessions»Historial de sesiones de acceso remoto (SSH, Telnet, WinBox, RDP). Quien gestiona el Acceso Remoto ve todas; los demás, solo las propias.
| Parámetro | Observación |
|---|---|
dias |
período en días (predeterminado: todo) |
grupo |
id del grupo (incluye subgrupos) |
pessoa |
id de la persona |
equipamento |
id del equipo |
protocolo |
ssh, telnet, winbox o rdp |
curl -H "Authorization: Bearer $V2_TOKEN" \ "https://dns.version2.network/api/pub/v1/sessions?dias=7&protocolo=ssh"[ { "id": "e1f2...", "equipamento": "BORDE-01", "protocolo": "ssh", "user": "Ana", "grupos": ["Matriz"], "started_at": "2026-11-04T18:00:00Z", "ended_at": "2026-11-04T18:12:30Z", "end_reason": "usuario", "bytes": 48213, "archived": false, "live": false }]Backup de configuración
Sección titulada «Backup de configuración»GET /backup/summary
Sección titulada «GET /backup/summary»Resumen del módulo Backup: equipos con backup y el estado de cada uno, rutinas, almacenamiento usado y la serie de los últimos días (los mismos datos de la pantalla Backup).
| Permiso | backup: ver (1) |
curl -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/backup/summaryRespuesta 200: objeto con equipamentos, rotinas, padrao, armazenamento y serie.
GET /hosts/{id}/backups
Sección titulada «GET /hosts/{id}/backups»Las versiones guardadas de un equipo (hasta 500, de la más reciente a la más antigua).
| Permiso | backup: ver (1) |
| Parámetros | id (ruta) — id del equipo |
curl -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/hosts/b2e4.../backups{ "versoes": [ { "id": "d4c3...", "at": "2026-11-04T03:00:00Z", "sha256": "9f...", "bytes": 18211, "marco": false } ] }Error 404 si el equipo no es de este cliente.
GET /backups/{id}
Sección titulada «GET /backups/{id}»El contenido de una versión (texto de la configuración, text/plain). Con ?analise=1, devuelve en JSON lo que el lector del fabricante entendió (interfaces, servicios, reglas, exposición) en vez del texto. La lectura queda en la auditoría (acesso.backup_visto).
| Permiso | Total en Backup o gestión del Acceso Remoto |
| Parámetros | id (ruta) — id de la versión; analise=1 (consulta, opcional) |
curl -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/backups/d4c3... -o borde-01.rscPOST /hosts/{id}/backup
Sección titulada «POST /hosts/{id}/backup»Hace el backup ahora (el mismo botón “Hacer ahora” del panel): se conecta por SSH, lee la configuración y guarda una versión nueva si cambió. No modifica nada en el equipo.
| Permiso | token de escritura + Total en Backup (o gestión del Acceso Remoto) |
| Parámetros | id (ruta) |
| Cuerpo | ninguno |
curl -X POST -H "Authorization: Bearer $V2_TOKEN" -H "Content-Type: application/json" \ https://dns.version2.network/api/pub/v1/hosts/b2e4.../backup{ "message": "Backup feito: versão nova guardada.", "nova_versao": true }Errores: 404 (equipo de otro cliente o inexistente), 409 (ya hay un backup de este equipo en curso), 422 (el equipo no respondió o la credencial falló; el mensaje dice el motivo).
Bloqueos DNS (RPZ)
Sección titulada «Bloqueos DNS (RPZ)»Las listas de bloqueo del módulo DNS recursivo (órdenes judiciales, oficios y listas internas). La activación y la revocación de una lista (que pueden exigir aprobación) siguen en el panel; la API cubre el ciclo de borrador (crear, consultar, editar, eliminar) y la exportación de los dominios.
GET /dns/blocks
Sección titulada «GET /dns/blocks»Lista las órdenes de bloqueo.
| Permiso | dns: ver (1) |
curl -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/dns/blocks{ "orders": [ { "id": "c3f5...", "kind": "interna", "reference": "Lista interna 01", "action": "nxdomain", "all_groups": true, "group_ids": [], "status": "draft", "created_at": "2026-11-04T18:20:00Z", "domains": 1 } ], "active_orders": 0, "active_domains": 0}GET /dns/blocks/{id}
Sección titulada «GET /dns/blocks/{id}»Detalles de una orden, con los dominios y los grupos afectados.
| Permiso | dns: ver (1) |
| Parámetros | id (ruta); q (consulta, opcional) — filtra los dominios por texto |
{ "order": { "id": "c3f5...", "kind": "interna", "reference": "Lista interna 01", "status": "draft", "action": "nxdomain", "all_groups": true, "domains": 1 }, "domains": [ { "domain": "example.net", "subdomains": false } ], "groups": []}GET /dns/blocks/{id}/domains.csv
Sección titulada «GET /dns/blocks/{id}/domains.csv»Los dominios de la orden en CSV (text/csv), para revisión o archivo.
curl -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/dns/blocks/c3f5.../domains.csv -o lista.csvPOST /dns/blocks
Sección titulada «POST /dns/blocks»Crea una orden (nace como borrador).
| Permiso | token de escritura + dns: escribir (2) |
Cuerpo:
| Campo | Tipo | Observación |
|---|---|---|
kind |
string | judicial, administrativa o interna |
reference |
string | número del proceso/oficio o nombre de la lista (hasta 200) |
authority |
string | órgano emisor (opcional) |
received_on |
string | fecha AAAA-MM-DD (opcional) |
notes |
string | observaciones (opcional) |
action |
string | nxdomain (predeterminado) o redirect |
redirect_v4 |
string | IP de la página de aviso, cuando action = redirect |
redirect_v6 |
string | ídem, IPv6 |
all_groups |
boolean | aplicar a todos los grupos |
group_ids |
string[] | grupos, cuando all_groups es falso |
domains |
string | dominios, uno por línea (o separados por coma/espacio); *. pide subdominios |
curl -X POST -H "Authorization: Bearer $V2_TOKEN" \ -H "Content-Type: application/json" \ -d '{"kind":"interna","reference":"Lista interna 01","all_groups":true,"domains":"example.net"}' \ https://dns.version2.network/api/pub/v1/dns/blocksRespuesta 200:
{ "id": "c3f5...", "domains": 1 }Errores: 400 con la lista de fields cuando algún dominio o campo es inválido (nada se guarda).
PUT /dns/blocks/{id}
Sección titulada «PUT /dns/blocks/{id}»Edita una orden en borrador (mismo cuerpo del POST).
| Permiso | token de escritura + dns: escribir (2) |
| Parámetros | id (ruta) |
Respuesta 200: { "id": "c3f5...", "domains": 1 }. Error 409 si la orden no está en borrador (active/revoque por el panel) o si el id no es de este cliente.
DELETE /dns/blocks/{id}
Sección titulada «DELETE /dns/blocks/{id}»Elimina una orden. Borrador: cualquier persona con escribir. Orden activa o revocada: solo Gerente, con un reason en el cuerpo (la auditoría guarda lo que había en ella).
| Permiso | token de escritura + dns: escribir (2); orden activa/revocada exige Gerente |
| Parámetros | id (ruta) |
| Cuerpo (opcional) | { "reason": "motivo" } — obligatorio para orden activa/revocada |
Respuesta 200: { "ok": true }.
DNS recursivo: operación (solo lectura)
Sección titulada «DNS recursivo: operación (solo lectura)»Los mismos datos de las pantallas Visión general, Estadísticas, Incidentes, Grupos y Nodes. Todos exigen dns: ver (1).
GET /dns/overview
Sección titulada «GET /dns/overview»Visión general: grupos con nodes activos y en línea, puntaje de salud, QPS, capacidad estimada, incidentes abiertos y avisos.
curl -H "Authorization: Bearer $V2_TOKEN" https://dns.version2.network/api/pub/v1/dns/overviewGET /dns/stats
Sección titulada «GET /dns/stats»Series de consultas (QPS, NXDOMAIN, SERVFAIL, latencia) y totales del período.
| Parámetro | Observación |
|---|---|
range |
1h, 6h, 24h (predeterminado), 7d, 30d o 90d |
group |
id del grupo (opcional) |
node |
id del node (opcional) |
curl -H "Authorization: Bearer $V2_TOKEN" \ "https://dns.version2.network/api/pub/v1/dns/stats?range=7d"GET /dns/incidents y GET /dns/incidents/{id}
Sección titulada «GET /dns/incidents y GET /dns/incidents/{id}»Incidentes (hasta 200) con MTTA y MTTR en segundos; ?status=open solo los abiertos. El detalle trae las alertas del incidente.
{ "incidents": [ { "id": "f0a1...", "title": "Node fuera de línea", "severity": "critical", "status": "open", "node_id": "7b...", "group_id": "9a...", "opened_at": "2026-11-04T12:00:00Z", "ack_at": null, "resolved_at": null, "cause": "", "alerts": 3 } ], "mtta_s": 120.5, "mttr_s": 900.0}GET /dns/groups y GET /dns/groups/{id}
Sección titulada «GET /dns/groups y GET /dns/groups/{id}»Grupos de nodes con anycast, enrutamiento, suscriptores, cantidad de nodes y prefijos, redundancia y estimación de capacidad. Los secretos (clave OSPF, contraseña BGP) no vuelven: solo ospf_key_set.
GET /dns/nodes, GET /dns/nodes/{id} y GET /dns/nodes/{id}/metrics
Sección titulada «GET /dns/nodes, GET /dns/nodes/{id} y GET /dns/nodes/{id}/metrics»Nodes del cliente (hostname, IPs, estado, salud, versión aplicada, QPS, grupo). Las métricas traen muestras de qps, cpu, mem, disk, nxdomain y servfail; ?minutes= de 1 a 1440 (predeterminado 60).
curl -H "Authorization: Bearer $V2_TOKEN" \ "https://dns.version2.network/api/pub/v1/dns/nodes/7b.../metrics?minutes=180"GET /dns/approvals y GET /dns/approvals/{id}
Sección titulada «GET /dns/approvals y GET /dns/approvals/{id}»Pedidos de aprobación (cambios que el flujo de aprobación del cliente retiene hasta que alguien decida). ?todos=1 incluye los ya decididos. Decidir sigue en el panel.
RPKI (solo lectura)
Sección titulada «RPKI (solo lectura)»Exigen rpki: ver (1). Crear CA, publicar ROAs y registrar routers siguen en el panel.
GET /rpki
Sección titulada «GET /rpki»Las CAs del cliente (ASN, etapa, avisos de la vigilancia, estado en Krill) y si el servicio está listo (ready).
GET /rpki/cas/{id}/roas
Sección titulada «GET /rpki/cas/{id}/roas»ROAs de la CA: prefijos cubiertos, ROAs publicadas y automáticas, anuncios inválidos o fuera de la cobertura.
GET /rpki/routers
Sección titulada «GET /rpki/routers»Routers habilitados para recibir las ROAs validadas por RTR y el estado de la conexión de cada uno.
Ejemplo completo (crear token → host → listar → backup → editar → eliminar)
Sección titulada «Ejemplo completo (crear token → host → listar → backup → editar → eliminar)»-
Genere un token de escritura en el panel (Gestión de la cuenta → Tokens de API, alcance “Lectura y escritura”) y guárdelo:
Ventana de terminal export V2_TOKEN="v2dns_a1b2c3d4e5f6a7b8_SECRETO..."export V2_API="https://dns.version2.network/api/pub/v1" -
Confirme el acceso (observe
scopeylevels):Ventana de terminal curl -H "Authorization: Bearer $V2_TOKEN" "$V2_API/whoami" -
Cree un equipo y guarde el
id:Ventana de terminal ID=$(curl -s -X POST -H "Authorization: Bearer $V2_TOKEN" \-H "Content-Type: application/json" \-d '{"name":"BORDE-01","address":"198.51.100.10","kind":"roteador","vendor":"mikrotik","ssh_port":22,"cred_mode":"salva","cred_user":"v2adm","cred_password":"...","backup":true,"grupos":[]}' \"$V2_API/hosts" | sed -n 's/.*"id":"\([^"]*\)".*/\1/p')echo "$ID" -
Liste los equipos y haga un backup ahora:
Ventana de terminal curl -H "Authorization: Bearer $V2_TOKEN" "$V2_API/hosts"curl -X POST -H "Authorization: Bearer $V2_TOKEN" -H "Content-Type: application/json" "$V2_API/hosts/$ID/backup"curl -H "Authorization: Bearer $V2_TOKEN" "$V2_API/hosts/$ID/backups" -
Edite el equipo (sin
cred_password, la contraseña guardada se mantiene):Ventana de terminal curl -X PUT -H "Authorization: Bearer $V2_TOKEN" \-H "Content-Type: application/json" \-d '{"name":"BORDE-01-RJ","address":"198.51.100.10","kind":"roteador","vendor":"mikrotik","ssh_port":22,"cred_mode":"salva","cred_user":"v2adm","backup":true,"grupos":[]}' \"$V2_API/hosts/$ID" -
Elimine el equipo:
Ventana de terminal curl -X DELETE -H "Authorization: Bearer $V2_TOKEN" "$V2_API/hosts/$ID" -
Para monitoreo, use un segundo token, de solo lectura, en otra máquina:
Ventana de terminal curl -H "Authorization: Bearer $V2_TOKEN_RO" "$V2_API/dns/overview"curl -H "Authorization: Bearer $V2_TOKEN_RO" "$V2_API/dns/incidents?status=open"curl -H "Authorization: Bearer $V2_TOKEN_RO" "$V2_API/backup/summary"
Lo que la API no hace, a propósito
Sección titulada «Lo que la API no hace, a propósito»- Acciones en equipos y nodes (abrir terminal o WinBox, reiniciar, actualizar el agente, desactivar anycast, probar la conexión): solo por el panel, con la persona presente.
- Activar o revocar bloqueos, decidir aprobaciones, modificar grupos, políticas, enrutamiento y prefijos: pasan por el flujo de aprobación y la auditoría del panel.
- Gestionar personas, invitaciones, perfiles y configuraciones del cliente y generar o revocar tokens con un token (un token no crea otros).
- Crear CA, publicar ROAs y registrar routers en RPKI.
Seguridad, en resumen
Sección titulada «Seguridad, en resumen»- El token aparece una vez y se guarda como hash; muéstrelo solo a quien lo necesite y nunca lo ponga en una URL, en un log o en código versionado.
- Guárdelo en una variable de entorno o en una bóveda de secretos.
- Genere un token por integración, con nombre claro y solo lectura siempre que alcance; así revoca solo lo que necesite.
- Prefiera la validez predeterminada (90 días) y rote los tokens de vez en cuando.
- Revoque de inmediato cualquier token que pueda haberse filtrado. Cambiar su contraseña también revoca todos sus tokens.
- Un token solo ve el cliente en que fue generado. Si su integración atiende a más de un cliente, genere un token en cada uno.