Skip to content

Public API (per-user token)

Automate the platform outside the panel: a script or an agent performs the same actions you would perform on screen, using an API token. The token is a door into the same logic as the panel, so it goes through the same controls: the customer it belongs to, your role (Manager, Editor or Viewer), the contracted modules and, on top of all that, the token’s scope (read-only or read and write). The token never grants more access than you have; if your role changes or you leave the customer, the token loses access too.

Who can: anyone in the customer generates and manages their own tokens. What the token can do is limited by your role and the chosen scope.

  1. One customer only. The token is valid for the customer it was generated in and for no other, under any circumstances. The customer is read from the token itself on the server; no API route accepts a customer identifier by path, query, body or header. Every data access runs isolated per customer in the database (RLS). An id from another customer answers 404, as if it did not exist.
  2. Scope is a ceiling, not an addition. A read-only token only performs GET; any POST, PUT or DELETE answers 403 before reaching the action. A read and write token remains limited by the current role of whoever generated it, checked on every call: a Viewer cannot generate a write token, and a write token of someone demoted to Viewer becomes read-only.
  3. No secret in the clear. The token value is shown once; only a hash is stored. The list, the audit trail and the logs show only the public identifier.

V2 team (platform administrators): an administrator’s token acts as an administrator inside the customer it was generated in (role admin, full level in every module of that customer), and stays bound to that customer. Treat it as an administrative credential: short validity, one per integration, revoke when done.

  1. In the menu, open Account management and click API tokens.
  2. Give it a name (for example backup script or DNS agent).
  3. Choose the scope: Read-only (GET) or Read and write. Prefer read-only; use write only when the integration needs to create, change or delete. If your role only allows viewing, the write option is disabled (and the server refuses with 403 even if someone forces the request).
  4. Choose the validity: 30 days, 90 days (recommended and default), 1 year or no expiration. An expired token answers 401.
  5. Click Generate token. The full value appears once — it starts with v2dns_. Copy it and store it somewhere safe (a secrets vault). It will not be shown again.

Only a hash of the secret is stored; not even Version2 can recover the value. If you lose the token, revoke (or rotate) it and use the new one.

Limits: up to 20 active tokens per person and up to 10 generations per hour.

On the same screen, the list shows your tokens with their public identifier (the v2dns_<identifier> part, without the secret), the scope, creation date, last use, validity and state. Click Revoke to disable a token immediately — integrations using it stop working at once. The row stays in the list (and in the audit trail) marked as revoked.

Click Rotate to replace the secret without recreating the configuration: a new token is generated with the same name, scope and remaining validity, and the old one is revoked in the same operation. The new value is shown once; swap it into your integration right away. Rotate periodically (for example every 90 days) and whenever you suspect a leak.

All your tokens are revoked automatically whenever your credential changes hands: password change, password reset via “Forgot my password”, recovery or reset of the two-step verifier. This is deliberate: a recovered account must not keep a token someone generated during unauthorized access. After recovering the account, generate new tokens.

Send the token in the Authorization header, with the Bearer scheme:

Authorization: Bearer v2dns_a1b2c3d4e5f6a7b8_SECRET...
  • Every API route requires a valid token. No token, or an invalid, revoked or expired token: 401 with the header WWW-Authenticate: Bearer realm="v2dns" (the response is generic and does not reveal whether the token exists).
  • The API uses neither cookies nor the browser session, so CSRF does not apply. That is why it is meant for server-to-server integration and agents, not for third-party browsers: CORS is not enabled.
  • The API token is not valid on the panel’s internal API (/api/v1/...), and the panel cookie is not valid on the public API.
  • Requests with a body (POST, PUT) need Content-Type: application/json.

All routes live under a versioned prefix:

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

The version in the path (v1) only changes for incompatible changes. New fields may be added to a response without a version bump, so your integration should ignore unknown fields.

Responses are JSON (Content-Type: application/json), except the .csv endpoints and backup content, which are text. Unknown fields in a request body are rejected with 400 (avoids silent errors from a mistyped field). A request body may be up to 2 MiB; each request has 60 s to complete.

Errors always follow the same format:

{ "error": "readable message", "fields": [ { "field": "field_name", "message": "what to fix" } ] }
Code When
400 Invalid body, missing field, unknown field, body too large
401 Token missing, invalid, revoked or expired (with WWW-Authenticate)
403 Read-only token on POST/PUT/DELETE; role does not allow the action; module not enabled for the customer
404 Resource not found (or from another customer, or not visible to you)
409 Conflict (for example editing a list that is not a draft, duplicate name, backup already running)
415 Missing Content-Type: application/json
422 The action was attempted and failed on the device side (for example a manual backup)
429 Request limit reached
500 Internal error (no internal details in the response)
  • Per token: up to 120 requests per minute (counted only for calls with the correct secret: someone who knows only the public identifier cannot lock your token).
  • Per IP: up to 300 requests per minute.

Beyond that, the API answers 429; wait and retry.

Every write (POST, PUT, DELETE) is recorded in the customer’s audit trail with who did it, which token (public identifier) and which route:

  • api.escrita — the action was executed (status 2xx); the detail of what changed is in the resource’s own event (for example acesso.equipamento_criado).
  • api.escrita_negada — the action was refused (read-only scope, insufficient role or validation error), with the returned status.

Token generation, rotation and revocation are audited too (conta.api_token_criado, conta.api_token_girado, conta.api_token_revogado).

Each module has a level: 0 none, 1 view, 2 write, 3 full. The default role applies equally to every module: Viewer = 1, Editor = 2, Manager = 3. The permissions below cite the minimum level required; remember that a read-only token only performs GET, whatever the level.


Paths are relative to the base https://dns.version2.network/api/pub/v1. In the examples, $V2_TOKEN is your token.

Module Method and path Permission
— GET /health none
Account GET /whoami valid token
Account GET /audit conta: full (3)
Remote Access GET /hosts, GET /hosts/{id} acesso: view (1)
Remote Access POST /hosts, PUT /hosts/{id}, DELETE /hosts/{id} write + inventory management
Remote Access GET /sessions acesso: view (1)
Backup GET /backup/summary backup: view (1)
Backup GET /hosts/{id}/backups backup: view (1)
Backup GET /backups/{id} backup: full (3) or Remote Access management
Backup POST /hosts/{id}/backup write + backup: full (3)
DNS GET /dns/blocks, GET /dns/blocks/{id}, GET /dns/blocks/{id}/domains.csv dns: view (1)
DNS POST /dns/blocks, PUT /dns/blocks/{id}, DELETE /dns/blocks/{id} write + dns: write (2)
DNS GET /dns/overview, GET /dns/stats, GET /dns/incidents, GET /dns/incidents/{id} dns: view (1)
DNS GET /dns/groups, GET /dns/groups/{id}, GET /dns/nodes, GET /dns/nodes/{id}, GET /dns/nodes/{id}/metrics dns: view (1)
DNS GET /dns/approvals, GET /dns/approvals/{id} dns: view (1)
RPKI GET /rpki, GET /rpki/cas/{id}/roas, GET /rpki/routers rpki: view (1)

Checks whether the API is up. The only endpoint without a token. Carries no customer data.

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

Shows the token’s fixed customer, scope, your role and the per-module levels. Useful for the integration to confirm what it can do.

Janela do 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": "Example ISP" },
"role": "gerente",
"levels": { "dns": 3, "rpki": 3, "acesso": 3, "backup": 3, "conta": 3 },
"modulos": ["dns", "rpki", "acesso", "backup"],
"token": "a1b2c3d4e5f6a7b8",
"scope": "escrita"
}

The customer’s audit trail (up to the 300 most recent events). Only for those with full level in Account management.

Parameter Note
q text to search (action, target, person)
modulo dns, rpki, acesso, backup or conta
from, to YYYY-MM-DD dates
Janela do 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" }
]

The devices of the Remote Access module (inventory shared with Backup). Credential passwords are never returned on read.

Lists the customer’s devices, groups and proxies.

Permission acesso: view (1)
Janela do terminal
curl -H "Authorization: Bearer $V2_TOKEN" \
https://dns.version2.network/api/pub/v1/hosts
{
"grupos": [ { "id": "9a1b...", "path": "HQ / Edge" } ],
"proxies": [ { "id": "5c7d...", "name": "HQ Connector", "online": true } ],
"equipamentos": [
{
"id": "b2e4...",
"name": "EDGE-01",
"address": "198.51.100.10",
"kind": "roteador",
"vendor": "mikrotik",
"ssh_port": 22,
"telnet_port": null,
"winbox_port": 8291,
"rdp_port": null,
"tags": ["edge"],
"grupos": ["9a1b..."],
"proxy": "HQ Connector",
"cred_mode": "salva",
"cred_user": "v2adm",
"has_secret": true,
"backup": false
}
],
"idle_minutes": 5,
"pode_gerir": true,
"pode_backup": true
}

Details of one device.

Permission acesso: view (1) — only visible if some rule grants it; managers see everything
Parameters id (path) — device id
Janela do terminal
curl -H "Authorization: Bearer $V2_TOKEN" \
https://dns.version2.network/api/pub/v1/hosts/b2e4...
{
"id": "b2e4...",
"name": "EDGE-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": "HQ Connector",
"idle_minutes": 5
}

Errors: 404 if the device does not exist (or belongs to another customer, or no rule grants it to you).

Creates a device.

Permission write token + Full in Remote Access or Backup (whoever manages the inventory)

Body:

Field Type Note
name string required, up to 64 characters
address string device IP (IPv4 or IPv6), no mask
kind string servidor, roteador or switch (default roteador)
vendor string linux/windows (server) or mikrotik/cisco/juniper/huawei/outro
ssh_port number or null provide the port of at least one protocol
telnet_port number or null
winbox_port number or null MikroTik only
rdp_port number or null Windows server only
tags string[] up to 32 tags
grupos string[] ids of groups the device belongs to
proxy_id string or null chosen proxy (null: inherits from group or default)
cred_mode string salva (stores the credential) or digitada (asks on every access)
cred_user string user, when cred_mode = salva
cred_password string password, when cred_mode = salva
backup boolean enables configuration backup (requires SSH and a stored credential, or backup_user)
backup_user, backup_password string dedicated backup credential (optional)
Janela do terminal
curl -X POST -H "Authorization: Bearer $V2_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"EDGE-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

Response 201:

{ "id": "b2e4..." }

Errors: 400 (invalid fields, with fields), 403 (read-only token or no management permission), 409 (duplicate name), 404 (group or proxy does not exist).

Edits a device. Same body as POST. Leave cred_password out to keep the stored password.

Permission write token + Full in Remote Access or Backup
Parameters id (path)
Janela do terminal
curl -X PUT -H "Authorization: Bearer $V2_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"EDGE-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...

Response 200: { "id": "b2e4..." }. Error 404 if the id is not from this customer.

Deletes a device (and its backup history).

Permission write token + Full in Remote Access or Backup
Parameters id (path)
Janela do terminal
curl -X DELETE -H "Authorization: Bearer $V2_TOKEN" \
https://dns.version2.network/api/pub/v1/hosts/b2e4...

Response 200: { "message": "Equipamento EDGE-01-RJ removido." }.

Remote access session history (SSH, Telnet, WinBox, RDP). Remote Access managers see all sessions; others only their own.

Parameter Note
dias period in days (default: everything)
grupo group id (includes subgroups)
pessoa person id
equipamento device id
protocolo ssh, telnet, winbox or rdp
Janela do terminal
curl -H "Authorization: Bearer $V2_TOKEN" \
"https://dns.version2.network/api/pub/v1/sessions?dias=7&protocolo=ssh"
[
{ "id": "e1f2...", "equipamento": "EDGE-01", "protocolo": "ssh", "user": "Ana", "grupos": ["HQ"],
"started_at": "2026-11-04T18:00:00Z", "ended_at": "2026-11-04T18:12:30Z", "end_reason": "usuario",
"bytes": 48213, "archived": false, "live": false }
]

Backup module summary: devices with backup and each one’s state, routines, storage used and the series for the last days (the same data as the Backup screen).

Permission backup: view (1)
Janela do terminal
curl -H "Authorization: Bearer $V2_TOKEN" \
https://dns.version2.network/api/pub/v1/backup/summary

Response 200: object with equipamentos, rotinas, padrao, armazenamento and serie.

The stored versions of one device (up to 500, newest first).

Permission backup: view (1)
Parameters id (path) — device id
Janela do 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 if the device is not from this customer.

The content of one version (configuration text, text/plain). With ?analise=1, returns as JSON what the vendor reader understood (interfaces, services, rules, exposure) instead of the text. The read is audited (acesso.backup_visto).

Permission Full in Backup or Remote Access management
Parameters id (path) — version id; analise=1 (query, optional)
Janela do terminal
curl -H "Authorization: Bearer $V2_TOKEN" \
https://dns.version2.network/api/pub/v1/backups/d4c3... -o edge-01.rsc

Backs up now (the same “Back up now” button as the panel): connects over SSH, reads the configuration and stores a new version if it changed. Changes nothing on the device.

Permission write token + Full in Backup (or Remote Access management)
Parameters id (path)
Body none
Janela do 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 }

Errors: 404 (device from another customer or nonexistent), 409 (a backup of this device is already running), 422 (the device did not answer or the credential failed; the message says why).


The block lists of the recursive DNS module (court orders, official notices and internal lists). Activating and revoking a list (which may require approval) stay in the panel; the API covers the draft cycle (create, read, edit, delete) and exporting the domains.

Lists the block orders.

Permission dns: view (1)
Janela do terminal
curl -H "Authorization: Bearer $V2_TOKEN" \
https://dns.version2.network/api/pub/v1/dns/blocks
{
"orders": [
{
"id": "c3f5...",
"kind": "interna",
"reference": "Internal list 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
}

Details of one order, with its domains and affected groups.

Permission dns: view (1)
Parameters id (path); q (query, optional) — filters domains by text
{
"order": { "id": "c3f5...", "kind": "interna", "reference": "Internal list 01", "status": "draft", "action": "nxdomain", "all_groups": true, "domains": 1 },
"domains": [ { "domain": "example.net", "subdomains": false } ],
"groups": []
}

The order’s domains as CSV (text/csv), for review or archiving.

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

Creates an order (born as a draft).

Permission write token + dns: write (2)

Body:

Field Type Note
kind string judicial, administrativa or interna
reference string case/notice number or list name (up to 200)
authority string issuing body (optional)
received_on string YYYY-MM-DD date (optional)
notes string notes (optional)
action string nxdomain (default) or redirect
redirect_v4 string IP of the notice page, when action = redirect
redirect_v6 string same, IPv6
all_groups boolean apply to all groups
group_ids string[] groups, when all_groups is false
domains string domains, one per line (or separated by comma/space); *. requests subdomains
Janela do terminal
curl -X POST -H "Authorization: Bearer $V2_TOKEN" \
-H "Content-Type: application/json" \
-d '{"kind":"interna","reference":"Internal list 01","all_groups":true,"domains":"example.net"}' \
https://dns.version2.network/api/pub/v1/dns/blocks

Response 200:

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

Errors: 400 with the fields list when a domain or field is invalid (nothing is saved).

Edits a draft order (same body as POST).

Permission write token + dns: write (2)
Parameters id (path)

Response 200: { "id": "c3f5...", "domains": 1 }. Error 409 if the order is not a draft (activate/revoke in the panel) or if the id is not from this customer.

Deletes an order. Draft: anyone with write. Active or revoked order: Manager only, with a reason in the body (the audit trail keeps what it contained).

Permission write token + dns: write (2); active/revoked order requires Manager
Parameters id (path)
Body (optional) { "reason": "reason" } — required for an active/revoked order

Response 200: { "ok": true }.


The same data as the Overview, Statistics, Incidents, Groups and Nodes screens. All require dns: view (1).

Overview: groups with active and online nodes, health score, QPS, estimated capacity, open incidents and warnings.

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

Query series (QPS, NXDOMAIN, SERVFAIL, latency) and period totals.

Parameter Note
range 1h, 6h, 24h (default), 7d, 30d or 90d
group group id (optional)
node node id (optional)
Janela do terminal
curl -H "Authorization: Bearer $V2_TOKEN" \
"https://dns.version2.network/api/pub/v1/dns/stats?range=7d"

GET /dns/incidents and GET /dns/incidents/{id}

Section titled “GET /dns/incidents and GET /dns/incidents/{id}”

Incidents (up to 200) with MTTA and MTTR in seconds; ?status=open for open ones only. The detail brings the incident’s alerts.

{
"incidents": [
{ "id": "f0a1...", "title": "Node down", "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
}

Node groups with anycast, routing, subscribers, node and prefix counts, redundancy and capacity estimate. Secrets (OSPF key, BGP password) are not returned: only ospf_key_set.

GET /dns/nodes, GET /dns/nodes/{id} and GET /dns/nodes/{id}/metrics

Section titled “GET /dns/nodes, GET /dns/nodes/{id} and GET /dns/nodes/{id}/metrics”

The customer’s nodes (hostname, IPs, state, health, applied version, QPS, group). Metrics bring samples of qps, cpu, mem, disk, nxdomain and servfail; ?minutes= from 1 to 1440 (default 60).

Janela do terminal
curl -H "Authorization: Bearer $V2_TOKEN" \
"https://dns.version2.network/api/pub/v1/dns/nodes/7b.../metrics?minutes=180"

GET /dns/approvals and GET /dns/approvals/{id}

Section titled “GET /dns/approvals and GET /dns/approvals/{id}”

Approval requests (changes the customer’s approval flow holds until someone decides). ?todos=1 includes decided ones. Deciding stays in the panel.


Require rpki: view (1). Creating a CA, publishing ROAs and registering routers stay in the panel.

The customer’s CAs (ASN, stage, monitoring warnings, state in Krill) and whether the service is ready (ready).

The CA’s ROAs: covered prefixes, published and automatic ROAs, invalid announcements or ones outside coverage.

Routers allowed to receive validated ROAs over RTR and each one’s connection state.


End-to-end example (create token → host → list → backup → edit → delete)

Section titled “End-to-end example (create token → host → list → backup → edit → delete)”
  1. Generate a write token in the panel (Account management → API tokens, scope “Read and write”) and store it:

    Janela do terminal
    export V2_TOKEN="v2dns_a1b2c3d4e5f6a7b8_SECRET..."
    export V2_API="https://dns.version2.network/api/pub/v1"
  2. Confirm access (note scope and levels):

    Janela do terminal
    curl -H "Authorization: Bearer $V2_TOKEN" "$V2_API/whoami"
  3. Create a device and keep the id:

    Janela do terminal
    ID=$(curl -s -X POST -H "Authorization: Bearer $V2_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name":"EDGE-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. List the devices and back up now:

    Janela do 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. Edit the device (without cred_password, the stored password is kept):

    Janela do terminal
    curl -X PUT -H "Authorization: Bearer $V2_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"name":"EDGE-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. Delete the device:

    Janela do terminal
    curl -X DELETE -H "Authorization: Bearer $V2_TOKEN" "$V2_API/hosts/$ID"
  7. For monitoring, use a second, read-only token on another machine:

    Janela do 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"
  • Actions on devices and nodes (open a terminal or WinBox, restart, update the agent, disable anycast, test a connection): panel only, with a person present.
  • Activate or revoke blocks, decide approvals, change groups, policies, routing and prefixes: they go through the panel’s approval flow and audit.
  • Manage people, invites, profiles and settings of the customer, and generate or revoke tokens with a token (a token does not create others).
  • Create a CA, publish ROAs and register routers in RPKI.
  • The token is shown once and stored as a hash; show it only to those who need it and never put it in a URL, a log or versioned code.
  • Keep it in an environment variable or a secrets vault.
  • Generate one token per integration, with a clear name and read-only whenever that suffices; that way you revoke only what you need.
  • Prefer the default validity (90 days) and rotate tokens from time to time.
  • Revoke immediately any token that may have leaked. Changing your password also revokes all your tokens.
  • A token only sees the customer it was generated in. If your integration serves more than one customer, generate a token in each.