API pública (token por usuário)
Objetivo
Seção intitulada “Objetivo”Automatizar a plataforma por fora do painel: um script ou um agent faz as mesmas ações que você faria na tela, usando um token de API. O token é a porta de entrada para a mesma lógica do painel, então passa pelos mesmos controles: o cliente a que pertence, o seu papel (Gerente, Editor ou Visualizador), os módulos contratados e, por cima de tudo isso, o escopo do token (somente leitura ou leitura e escrita). O token nunca dá mais acesso do que você tem; se o seu papel mudar ou você sair do cliente, o token perde o acesso junto.
Quem pode: qualquer pessoa do cliente gera e gerencia os próprios tokens. O que o token faz é limitado ao seu papel e ao escopo escolhido.
As três garantias
Seção intitulada “As três garantias”- Um cliente só. O token vale para o cliente em que foi gerado e para nenhum outro, em nenhuma circunstância. O cliente é lido do próprio token no servidor; nenhuma rota da API aceita um identificador de cliente por caminho, parâmetro, corpo ou cabeçalho. Todo acesso a dados roda isolado por cliente no banco (RLS). Um
idde outro cliente responde404, como se não existisse. - Escopo é teto, não acréscimo. Um token somente leitura só faz
GET; qualquerPOST,PUTouDELETEresponde403antes de chegar à ação. Um token de leitura e escrita continua limitado ao papel atual de quem o gerou, conferido a cada chamada: um Visualizador não consegue gerar token de escrita, e um token de escrita de alguém que virou Visualizador passa a só ler. - Nada de segredo em claro. O valor do token aparece uma única vez; no banco fica só um hash. A lista, a auditoria e os logs mostram apenas o identificador público.
Equipe V2 (administradores da plataforma): o token de um administrador age como administrador dentro do cliente em que foi gerado (papel
admin, nível total em todos os módulos daquele cliente), e continua preso a esse cliente. Trate esse token com o cuidado de uma credencial administrativa: validade curta, um por integração, e revogue ao terminar.
Gerar um token
Seção intitulada “Gerar um token”- No menu, abra Gestão da conta e clique em Tokens de API.
- Dê um nome (por exemplo,
script de backupouagent de DNS). - Escolha o escopo: Somente leitura (GET) ou Leitura e escrita. Prefira somente leitura; escrita só quando a integração precisar criar, alterar ou excluir. Se o seu papel só permite ver, a opção de escrita aparece desabilitada (e o servidor recusa com
403mesmo que alguém force o pedido). - Escolha a validade: 30 dias, 90 dias (recomendado e padrão), 1 ano ou sem expiração. Um token expirado responde
401. - Clique em Gerar token. O valor completo aparece uma única vez — começa com
v2dns_. Copie e guarde em lugar seguro (um cofre de segredos). Ele não será mostrado de novo.
No banco guardamos apenas um hash do segredo; nem a Version2 consegue recuperar o valor. Se você perder o token, revogue (ou gire) e use o novo.
Limites: até 20 tokens ativos por pessoa e até 10 gerações por hora.
Revogar
Seção intitulada “Revogar”Na mesma tela, a lista mostra seus tokens com o identificador público (o trecho v2dns_<identificador>, sem o segredo), o escopo, quando foi criado, o último uso, a validade e o estado. Clique em Revogar para desativar um token na hora — integrações que o usam param de funcionar imediatamente. A linha continua na lista (e na auditoria) marcada como revogada.
Girar (rotação)
Seção intitulada “Girar (rotação)”Clique em Girar para trocar o segredo sem recriar a configuração: um token novo é gerado com o mesmo nome, escopo e validade restante, e o antigo é revogado na mesma operação. O valor novo aparece uma vez; troque-o na sua integração em seguida. Use a rotação periodicamente (por exemplo, a cada 90 dias) e sempre que houver suspeita de vazamento.
Revogação automática
Seção intitulada “Revogação automática”Todos os seus tokens são revogados automaticamente quando a sua credencial muda de mãos: troca de senha, redefinição de senha por “Esqueci minha senha”, recuperação ou redefinição do verificador em duas etapas. É de propósito: uma conta recuperada não pode ficar com um token que alguém tenha gerado durante um acesso indevido. Depois de recuperar a conta, gere tokens novos.
Autenticação
Seção intitulada “Autenticação”Envie o token no cabeçalho Authorization, no esquema Bearer:
Authorization: Bearer v2dns_a1b2c3d4e5f6a7b8_SEGREDO...- Toda rota da API exige um token válido. Sem token, ou com token inválido, revogado ou expirado:
401com o cabeçalhoWWW-Authenticate: Bearer realm="v2dns"(a resposta é genérica e não revela se o token existe). - A API não usa cookies nem a sessão do navegador, então CSRF não se aplica. Por isso ela é para integração server-to-server e agents, não para o navegador de terceiros: não há CORS liberado.
- O token da API não vale na API interna do painel (
/api/v1/...), e o cookie do painel não vale na API pública. - Requisições com corpo (POST, PUT) precisam de
Content-Type: application/json.
Base e versionamento
Seção intitulada “Base e versionamento”Todas as rotas ficam sob um prefixo com versão:
https://dns.version2.network/api/pub/v1A versão no caminho (v1) só muda em alterações incompatíveis. Campos novos podem ser acrescentados a uma resposta sem trocar a versão, então a sua integração deve ignorar campos que não conhece.
Formato das respostas e erros
Seção intitulada “Formato das respostas e erros”As respostas são JSON (Content-Type: application/json), salvo os endpoints .csv e o conteúdo de backup, que são texto. Campos desconhecidos no corpo de uma requisição são recusados com 400 (evita erro silencioso por um campo digitado errado). O corpo de uma requisição pode ter até 2 MiB; cada requisição tem 60 s para terminar.
Erros seguem sempre o mesmo formato:
{ "error": "mensagem legível", "fields": [ { "field": "nome_do_campo", "message": "o que corrigir" } ] }| Código | Quando |
|---|---|
400 |
Corpo inválido, campo faltando, campo desconhecido, corpo grande demais |
401 |
Token ausente, inválido, revogado ou expirado (com WWW-Authenticate) |
403 |
Token somente leitura em POST/PUT/DELETE; o papel não permite a ação; módulo não habilitado para o cliente |
404 |
Recurso não encontrado (ou de outro cliente, ou sem permissão para vê-lo) |
409 |
Conflito (por exemplo, editar uma lista que não está em rascunho, nome repetido, backup já em andamento) |
415 |
Faltou Content-Type: application/json |
422 |
A ação foi tentada e falhou do lado do equipamento (por exemplo, backup manual) |
429 |
Limite de requisições atingido |
500 |
Erro interno (sem detalhes internos na resposta) |
Limites de uso
Seção intitulada “Limites de uso”- Por token: até 120 requisições por minuto (conta só para chamadas com o segredo correto: alguém que conheça apenas o identificador público não consegue travar o seu token).
- Por IP: até 300 requisições por minuto.
Acima disso, a API responde 429; aguarde e tente de novo.
Auditoria
Seção intitulada “Auditoria”Toda escrita (POST, PUT, DELETE) fica na auditoria do cliente com quem fez, qual token (identificador público) e qual rota:
api.escrita— a ação foi executada (status2xx); o detalhe do que mudou está no evento do próprio recurso (por exemplo,acesso.equipamento_criado).api.escrita_negada— a ação foi recusada (escopo somente leitura, papel insuficiente ou erro de validação), com o status devolvido.
A geração, a rotação e a revogação de tokens também ficam na auditoria (conta.api_token_criado, conta.api_token_girado, conta.api_token_revogado).
Níveis por módulo
Seção intitulada “Níveis por módulo”Cada módulo tem um nível: 0 nenhum, 1 ver, 2 escrever, 3 total. O papel padrão vale igual em todos os módulos: Visualizador = 1, Editor = 2, Gerente = 3. As permissões abaixo citam o nível mínimo exigido; lembre que um token somente leitura só faz GET, qualquer que seja o nível.
Endpoints
Seção intitulada “Endpoints”Os caminhos são relativos à base https://dns.version2.network/api/pub/v1. Nos exemplos, $V2_TOKEN é o seu token.
| Módulo | Método e caminho | Permissão |
|---|---|---|
| — | GET /health |
nenhuma |
| Conta | GET /whoami |
token válido |
| Conta | GET /audit |
conta: total (3) |
| Acesso Remoto | GET /hosts, GET /hosts/{id} |
acesso: ver (1) |
| Acesso Remoto | POST /hosts, PUT /hosts/{id}, DELETE /hosts/{id} |
escrita + gestão do cadastro |
| Acesso 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) ou gestão do Acesso Remoto |
| Backup | POST /hosts/{id}/backup |
escrita + 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} |
escrita + dns: escrever (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
Seção intitulada “GET /health”Verifica se a API está no ar. Único endpoint sem token. Não traz dados do cliente.
curl https://dns.version2.network/api/pub/v1/health{ "status": "ok" }GET /whoami
Seção intitulada “GET /whoami”Mostra o cliente fixo do token, o escopo, o seu papel e os níveis por módulo. Útil para a integração confirmar o que pode fazer.
curl -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/whoami{ "tenant": { "id": "3f2a...", "name": "Provedor Exemplo" }, "role": "gerente", "levels": { "dns": 3, "rpki": 3, "acesso": 3, "backup": 3, "conta": 3 }, "modulos": ["dns", "rpki", "acesso", "backup"], "token": "a1b2c3d4e5f6a7b8", "scope": "escrita"}GET /audit
Seção intitulada “GET /audit”A trilha de auditoria do cliente (até 300 eventos mais recentes). Só para quem tem total em Gestão da conta.
| Parâmetro | Observação |
|---|---|
q |
texto a procurar (ação, alvo, pessoa) |
modulo |
dns, rpki, acesso, backup ou conta |
from, to |
datas 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" }]Equipamentos (Acesso Remoto)
Seção intitulada “Equipamentos (Acesso Remoto)”Os equipamentos do módulo Acesso Remoto (cadastro compartilhado com o Backup). As senhas das credenciais nunca voltam na leitura.
GET /hosts
Seção intitulada “GET /hosts”Lista os equipamentos, grupos e proxies do cliente.
| Permissão | acesso: ver (1) |
curl -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/hosts{ "grupos": [ { "id": "9a1b...", "path": "Matriz / Borda" } ], "proxies": [ { "id": "5c7d...", "name": "Conector Matriz", "online": true } ], "equipamentos": [ { "id": "b2e4...", "name": "BORDA-01", "address": "198.51.100.10", "kind": "roteador", "vendor": "mikrotik", "ssh_port": 22, "telnet_port": null, "winbox_port": 8291, "rdp_port": null, "tags": ["borda"], "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}
Seção intitulada “GET /hosts/{id}”Detalhes de um equipamento.
| Permissão | acesso: ver (1) — só vê quem alguma regra libera; quem gere vê tudo |
| Parâmetros | id (caminho) — id do equipamento |
curl -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/hosts/b2e4...{ "id": "b2e4...", "name": "BORDA-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}Erros: 404 se o equipamento não existe (ou é de outro cliente, ou nenhuma regra o libera para você).
POST /hosts
Seção intitulada “POST /hosts”Cria um equipamento.
| Permissão | token de escrita + Total no Acesso Remoto ou no Backup (quem gere o cadastro) |
Corpo:
| Campo | Tipo | Observação |
|---|---|---|
name |
string | obrigatório, até 64 caracteres |
address |
string | IP do equipamento (IPv4 ou IPv6), sem máscara |
kind |
string | servidor, roteador ou switch (padrão roteador) |
vendor |
string | linux/windows (servidor) ou mikrotik/cisco/juniper/huawei/outro |
ssh_port |
número ou null | informe a porta de ao menos um protocolo |
telnet_port |
número ou null | |
winbox_port |
número ou null | só MikroTik |
rdp_port |
número ou null | só servidor Windows |
tags |
string[] | até 32 etiquetas |
grupos |
string[] | ids de grupos a que o equipamento pertence |
proxy_id |
string ou null | proxy escolhido (null: herda do grupo ou o padrão) |
cred_mode |
string | salva (guarda a credencial) ou digitada (pede a cada acesso) |
cred_user |
string | usuário, quando cred_mode = salva |
cred_password |
string | senha, quando cred_mode = salva |
backup |
boolean | liga o backup de configuração (exige SSH e credencial salva, ou backup_user) |
backup_user, backup_password |
string | credencial própria do backup (opcional) |
curl -X POST -H "Authorization: Bearer $V2_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"BORDA-01","address":"198.51.100.10","kind":"roteador","vendor":"mikrotik","ssh_port":22,"cred_mode":"digitada","grupos":[]}' \ https://dns.version2.network/api/pub/v1/hostsResposta 201:
{ "id": "b2e4..." }Erros: 400 (campos inválidos, com fields), 403 (token somente leitura ou sem permissão de gestão), 409 (nome repetido), 404 (grupo ou proxy inexistente).
PUT /hosts/{id}
Seção intitulada “PUT /hosts/{id}”Edita um equipamento. Mesmo corpo do POST. Deixe cred_password de fora para manter a senha salva.
| Permissão | token de escrita + Total no Acesso Remoto ou no Backup |
| Parâmetros | id (caminho) |
curl -X PUT -H "Authorization: Bearer $V2_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name":"BORDA-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...Resposta 200: { "id": "b2e4..." }. Erro 404 se o id não é deste cliente.
DELETE /hosts/{id}
Seção intitulada “DELETE /hosts/{id}”Exclui um equipamento (e o histórico de backup dele).
| Permissão | token de escrita + Total no Acesso Remoto ou no Backup |
| Parâmetros | id (caminho) |
curl -X DELETE -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/hosts/b2e4...Resposta 200: { "message": "Equipamento BORDA-01-RJ removido." }.
GET /sessions
Seção intitulada “GET /sessions”Histórico de sessões de acesso remoto (SSH, Telnet, WinBox, RDP). Quem gere o Acesso Remoto vê todas; os demais, só as próprias.
| Parâmetro | Observação |
|---|---|
dias |
período em dias (padrão: tudo) |
grupo |
id do grupo (inclui subgrupos) |
pessoa |
id da pessoa |
equipamento |
id do equipamento |
protocolo |
ssh, telnet, winbox ou rdp |
curl -H "Authorization: Bearer $V2_TOKEN" \ "https://dns.version2.network/api/pub/v1/sessions?dias=7&protocolo=ssh"[ { "id": "e1f2...", "equipamento": "BORDA-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 configuração
Seção intitulada “Backup de configuração”GET /backup/summary
Seção intitulada “GET /backup/summary”Resumo do módulo Backup: equipamentos com backup e o estado de cada um, rotinas, armazenamento usado e a série dos últimos dias (os mesmos dados da tela Backup).
| Permissão | backup: ver (1) |
curl -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/backup/summaryResposta 200: objeto com equipamentos, rotinas, padrao, armazenamento e serie.
GET /hosts/{id}/backups
Seção intitulada “GET /hosts/{id}/backups”As versões guardadas de um equipamento (até 500, da mais recente para a mais antiga).
| Permissão | backup: ver (1) |
| Parâmetros | id (caminho) — id do equipamento |
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 } ] }Erro 404 se o equipamento não é deste cliente.
GET /backups/{id}
Seção intitulada “GET /backups/{id}”O conteúdo de uma versão (texto da configuração, text/plain). Com ?analise=1, devolve em JSON o que o leitor do fabricante entendeu (interfaces, serviços, regras, exposição) em vez do texto. A leitura fica na auditoria (acesso.backup_visto).
| Permissão | Total no Backup ou gestão do Acesso Remoto |
| Parâmetros | id (caminho) — id da versão; analise=1 (consulta, opcional) |
curl -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/backups/d4c3... -o borda-01.rscPOST /hosts/{id}/backup
Seção intitulada “POST /hosts/{id}/backup”Faz o backup agora (o mesmo botão “Fazer agora” do painel): conecta por SSH, lê a configuração e guarda uma versão nova se ela mudou. Não altera nada no equipamento.
| Permissão | token de escrita + Total no Backup (ou gestão do Acesso Remoto) |
| Parâmetros | id (caminho) |
| Corpo | nenhum |
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 }Erros: 404 (equipamento de outro cliente ou inexistente), 409 (já há um backup deste equipamento em andamento), 422 (o equipamento não respondeu ou a credencial falhou; a mensagem diz o motivo).
Bloqueios DNS (RPZ)
Seção intitulada “Bloqueios DNS (RPZ)”As listas de bloqueio do módulo DNS recursivo (ordens judiciais, ofícios e listas internas). A ativação e a revogação de uma lista (que podem exigir aprovação) continuam no painel; a API cobre o ciclo de rascunho (criar, consultar, editar, excluir) e a exportação dos domínios.
GET /dns/blocks
Seção intitulada “GET /dns/blocks”Lista as ordens de bloqueio.
| Permissão | 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}
Seção intitulada “GET /dns/blocks/{id}”Detalhes de uma ordem, com os domínios e os grupos afetados.
| Permissão | dns: ver (1) |
| Parâmetros | id (caminho); q (consulta, opcional) — filtra os domínios 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
Seção intitulada “GET /dns/blocks/{id}/domains.csv”Os domínios da ordem em CSV (text/csv), para conferência ou arquivo.
curl -H "Authorization: Bearer $V2_TOKEN" \ https://dns.version2.network/api/pub/v1/dns/blocks/c3f5.../domains.csv -o lista.csvPOST /dns/blocks
Seção intitulada “POST /dns/blocks”Cria uma ordem (nasce como rascunho).
| Permissão | token de escrita + dns: escrever (2) |
Corpo:
| Campo | Tipo | Observação |
|---|---|---|
kind |
string | judicial, administrativa ou interna |
reference |
string | número do processo/ofício ou nome da lista (até 200) |
authority |
string | órgão emissor (opcional) |
received_on |
string | data AAAA-MM-DD (opcional) |
notes |
string | observações (opcional) |
action |
string | nxdomain (padrão) ou redirect |
redirect_v4 |
string | IP da página de aviso, quando action = redirect |
redirect_v6 |
string | idem, IPv6 |
all_groups |
boolean | aplicar a todos os grupos |
group_ids |
string[] | grupos, quando all_groups é falso |
domains |
string | domínios, um por linha (ou separados por vírgula/espaço); *. pede subdomínios |
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/blocksResposta 200:
{ "id": "c3f5...", "domains": 1 }Erros: 400 com a lista de fields quando algum domínio ou campo é inválido (nada é gravado).
PUT /dns/blocks/{id}
Seção intitulada “PUT /dns/blocks/{id}”Edita uma ordem em rascunho (mesmo corpo do POST).
| Permissão | token de escrita + dns: escrever (2) |
| Parâmetros | id (caminho) |
Resposta 200: { "id": "c3f5...", "domains": 1 }. Erro 409 se a ordem não estiver em rascunho (ative/revogue pelo painel) ou se o id não for deste cliente.
DELETE /dns/blocks/{id}
Seção intitulada “DELETE /dns/blocks/{id}”Exclui uma ordem. Rascunho: qualquer pessoa com escrever. Ordem ativa ou revogada: só Gerente, com um reason no corpo (a auditoria guarda o que havia nela).
| Permissão | token de escrita + dns: escrever (2); ordem ativa/revogada exige Gerente |
| Parâmetros | id (caminho) |
| Corpo (opcional) | { "reason": "motivo" } — obrigatório para ordem ativa/revogada |
Resposta 200: { "ok": true }.
DNS recursivo: operação (somente leitura)
Seção intitulada “DNS recursivo: operação (somente leitura)”Os mesmos dados das telas Visão geral, Estatísticas, Incidentes, Grupos e Nodes. Todos exigem dns: ver (1).
GET /dns/overview
Seção intitulada “GET /dns/overview”Visão geral: grupos com nodes ativos e online, pontuação de saúde, QPS, capacidade estimada, incidentes abertos e avisos.
curl -H "Authorization: Bearer $V2_TOKEN" https://dns.version2.network/api/pub/v1/dns/overviewGET /dns/stats
Seção intitulada “GET /dns/stats”Séries de consultas (QPS, NXDOMAIN, SERVFAIL, latência) e totais do período.
| Parâmetro | Observação |
|---|---|
range |
1h, 6h, 24h (padrão), 7d, 30d ou 90d |
group |
id do grupo (opcional) |
node |
id do node (opcional) |
curl -H "Authorization: Bearer $V2_TOKEN" \ "https://dns.version2.network/api/pub/v1/dns/stats?range=7d"GET /dns/incidents e GET /dns/incidents/{id}
Seção intitulada “GET /dns/incidents e GET /dns/incidents/{id}”Incidentes (até 200) com MTTA e MTTR em segundos; ?status=open só os abertos. O detalhe traz os alertas do incidente.
{ "incidents": [ { "id": "f0a1...", "title": "Node fora do ar", "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 e GET /dns/groups/{id}
Seção intitulada “GET /dns/groups e GET /dns/groups/{id}”Grupos de nodes com anycast, roteamento, assinantes, quantidade de nodes e prefixos, redundância e estimativa de capacidade. Segredos (chave OSPF, senha BGP) não voltam: só ospf_key_set.
GET /dns/nodes, GET /dns/nodes/{id} e GET /dns/nodes/{id}/metrics
Seção intitulada “GET /dns/nodes, GET /dns/nodes/{id} e GET /dns/nodes/{id}/metrics”Nodes do cliente (hostname, IPs, estado, saúde, versão aplicada, QPS, grupo). As métricas trazem amostras de qps, cpu, mem, disk, nxdomain e servfail; ?minutes= de 1 a 1440 (padrão 60).
curl -H "Authorization: Bearer $V2_TOKEN" \ "https://dns.version2.network/api/pub/v1/dns/nodes/7b.../metrics?minutes=180"GET /dns/approvals e GET /dns/approvals/{id}
Seção intitulada “GET /dns/approvals e GET /dns/approvals/{id}”Pedidos de aprovação (mudanças que o fluxo de aprovação do cliente segura até alguém decidir). ?todos=1 inclui os já decididos. Decidir continua no painel.
RPKI (somente leitura)
Seção intitulada “RPKI (somente leitura)”Exigem rpki: ver (1). Criar CA, publicar ROAs e cadastrar roteadores continuam no painel.
GET /rpki
Seção intitulada “GET /rpki”As CAs do cliente (ASN, estágio, avisos da vigilância, estado no Krill) e se o serviço está pronto (ready).
GET /rpki/cas/{id}/roas
Seção intitulada “GET /rpki/cas/{id}/roas”ROAs da CA: prefixos cobertos, ROAs publicadas e as automáticas, anúncios inválidos ou fora da cobertura.
GET /rpki/routers
Seção intitulada “GET /rpki/routers”Roteadores liberados para receber as ROAs validadas por RTR e o estado da conexão de cada um.
Exemplo completo (criar token → host → listar → backup → editar → excluir)
Seção intitulada “Exemplo completo (criar token → host → listar → backup → editar → excluir)”-
Gere um token de escrita no painel (Gestão da conta → Tokens de API, escopo “Leitura e escrita”) e guarde-o:
Janela do terminal export V2_TOKEN="v2dns_a1b2c3d4e5f6a7b8_SEGREDO..."export V2_API="https://dns.version2.network/api/pub/v1" -
Confirme o acesso (repare em
scopeelevels):Janela do terminal curl -H "Authorization: Bearer $V2_TOKEN" "$V2_API/whoami" -
Crie um equipamento e guarde o
id:Janela do terminal ID=$(curl -s -X POST -H "Authorization: Bearer $V2_TOKEN" \-H "Content-Type: application/json" \-d '{"name":"BORDA-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 os equipamentos e faça um backup agora:
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" -
Edite o equipamento (sem
cred_password, a senha salva é mantida):Janela do terminal curl -X PUT -H "Authorization: Bearer $V2_TOKEN" \-H "Content-Type: application/json" \-d '{"name":"BORDA-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" -
Exclua o equipamento:
Janela do terminal curl -X DELETE -H "Authorization: Bearer $V2_TOKEN" "$V2_API/hosts/$ID" -
Para monitoramento, use um segundo token, somente leitura, em outra máquina:
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"
O que a API não faz, de propósito
Seção intitulada “O que a API não faz, de propósito”- Ações em equipamentos e nodes (abrir terminal ou WinBox, reiniciar, atualizar agente, desativar anycast, testar conexão): só pelo painel, com a pessoa presente.
- Ativar ou revogar bloqueios, decidir aprovações, alterar grupos, políticas, roteamento e prefixos: passam pelo fluxo de aprovação e pela auditoria do painel.
- Gerir pessoas, convites, perfis e configurações do cliente e gerar ou revogar tokens por token (um token não cria outros).
- Criar CA, publicar ROAs e cadastrar roteadores no RPKI.
Segurança, em resumo
Seção intitulada “Segurança, em resumo”- O token aparece uma vez e é guardado como hash; mostre-o só a quem precisa e nunca o coloque em URL, em log ou no código versionado.
- Guarde-o em variável de ambiente ou num cofre de segredos.
- Gere um token por integração, com nome claro e somente leitura sempre que bastar; assim você revoga só o que precisar.
- Prefira a validade padrão (90 dias) e gire os tokens de tempos em tempos.
- Revogue na hora qualquer token que possa ter vazado. Trocar a sua senha também revoga todos os seus tokens.
- Um token só enxerga o cliente em que foi gerado. Se a sua integração atende mais de um cliente, gere um token em cada um.