Ir al contenido

API pública (token por usuario)

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.

  1. 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 id de otro cliente responde 404, como si no existiera.
  2. El alcance es un techo, no un añadido. Un token de solo lectura solo hace GET; cualquier POST, PUT o DELETE responde 403 antes 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.
  3. 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.

  1. En el menú, abra Gestión de la cuenta y haga clic en Tokens de API.
  2. Dele un nombre (por ejemplo, script de backup o agent de DNS).
  3. 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 403 aunque alguien fuerce el pedido).
  4. Elija la validez: 30 días, 90 días (recomendado y predeterminado), 1 año o sin expiración. Un token expirado responde 401.
  5. 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.

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.

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.

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: 401 con el encabezado WWW-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.

Todas las rutas están bajo un prefijo con versión:

https://dns.version2.network/api/pub/v1

La 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.

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)
  • 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.

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ó (estado 2xx); 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).

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.


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)

Verifica si la API está en línea. Único endpoint sin token. No trae datos del cliente.

Ventana de terminal
curl https://dns.version2.network/api/pub/v1/health
{ "status": "ok" }

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.

Ventana de terminal
curl -H "Authorization: Bearer $V2_TOKEN" \
https://dns.version2.network/api/pub/v1/whoami
{
"user": { "id": "7c9e...", "username": "[email protected]", "name": "Ana" },
"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"
}

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
Ventana de terminal
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" }
]

Los equipos del módulo Acceso Remoto (inventario compartido con Backup). Las contraseñas de las credenciales nunca vuelven en la lectura.

Lista los equipos, grupos y proxies del cliente.

Permiso acesso: ver (1)
Ventana de terminal
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
}

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
Ventana de terminal
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).

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)
Ventana de terminal
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/hosts

Respuesta 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).

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)
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":"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.

Elimina un equipo (y su historial de backup).

Permiso token de escritura + Total en Acceso Remoto o en Backup
Parámetros id (ruta)
Ventana de terminal
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." }.

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
Ventana de terminal
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 }
]

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)
Ventana de terminal
curl -H "Authorization: Bearer $V2_TOKEN" \
https://dns.version2.network/api/pub/v1/backup/summary

Respuesta 200: objeto con equipamentos, rotinas, padrao, armazenamento y serie.

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
Ventana de terminal
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.

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)
Ventana de terminal
curl -H "Authorization: Bearer $V2_TOKEN" \
https://dns.version2.network/api/pub/v1/backups/d4c3... -o borde-01.rsc

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
Ventana de terminal
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).


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.

Lista las órdenes de bloqueo.

Permiso dns: ver (1)
Ventana de terminal
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
}

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": []
}

Los dominios de la orden en CSV (text/csv), para revisión o archivo.

Ventana de terminal
curl -H "Authorization: Bearer $V2_TOKEN" \
https://dns.version2.network/api/pub/v1/dns/blocks/c3f5.../domains.csv -o lista.csv

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
Ventana de terminal
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/blocks

Respuesta 200:

{ "id": "c3f5...", "domains": 1 }

Errores: 400 con la lista de fields cuando algún dominio o campo es inválido (nada se guarda).

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.

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 }.


Los mismos datos de las pantallas Visión general, Estadísticas, Incidentes, Grupos y Nodes. Todos exigen dns: ver (1).

Visión general: grupos con nodes activos y en línea, puntaje de salud, QPS, capacidad estimada, incidentes abiertos y avisos.

Ventana de terminal
curl -H "Authorization: Bearer $V2_TOKEN" https://dns.version2.network/api/pub/v1/dns/overview

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)
Ventana de terminal
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
}

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).

Ventana de terminal
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.


Exigen rpki: ver (1). Crear CA, publicar ROAs y registrar routers siguen en el panel.

Las CAs del cliente (ASN, etapa, avisos de la vigilancia, estado en Krill) y si el servicio está listo (ready).

ROAs de la CA: prefijos cubiertos, ROAs publicadas y automáticas, anuncios inválidos o fuera de la cobertura.

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)»
  1. 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"
  2. Confirme el acceso (observe scope y levels):

    Ventana de terminal
    curl -H "Authorization: Bearer $V2_TOKEN" "$V2_API/whoami"
  3. 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"
  4. 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"
  5. 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"
  6. Elimine el equipo:

    Ventana de terminal
    curl -X DELETE -H "Authorization: Bearer $V2_TOKEN" "$V2_API/hosts/$ID"
  7. 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"
  • 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.
  • 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.