Pular para o conteúdo

API pública (token por usuário)

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.

  1. 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 id de outro cliente responde 404, como se não existisse.
  2. Escopo é teto, não acréscimo. Um token somente leitura só faz GET; qualquer POST, PUT ou DELETE responde 403 antes 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.
  3. 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.

  1. No menu, abra Gestão da conta e clique em Tokens de API.
  2. Dê um nome (por exemplo, script de backup ou agent de DNS).
  3. 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 403 mesmo que alguém force o pedido).
  4. Escolha a validade: 30 dias, 90 dias (recomendado e padrão), 1 ano ou sem expiração. Um token expirado responde 401.
  5. 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.

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.

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.

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.

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: 401 com o cabeçalho WWW-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.

Todas as rotas ficam sob um prefixo com versão:

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

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

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

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

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.


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)

Verifica se a API está no ar. Único endpoint sem token. Não traz dados do cliente.

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

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.

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

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

Os equipamentos do módulo Acesso Remoto (cadastro compartilhado com o Backup). As senhas das credenciais nunca voltam na leitura.

Lista os equipamentos, grupos e proxies do cliente.

Permissão acesso: ver (1)
Janela do terminal
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
}

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
Janela do terminal
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ê).

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)
Janela do terminal
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/hosts

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

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)
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":"digitada","grupos":[]}' \
https://dns.version2.network/api/pub/v1/hosts/b2e4...

Resposta 200: { "id": "b2e4..." }. Erro 404 se o id não é deste cliente.

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)
Janela do terminal
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." }.

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
Janela do terminal
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 }
]

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

Resposta 200: objeto com equipamentos, rotinas, padrao, armazenamento e serie.

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

Erro 404 se o equipamento não é deste cliente.

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

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

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


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.

Lista as ordens de bloqueio.

Permissão dns: ver (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": "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
}

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

Os domínios da ordem em CSV (text/csv), para conferência ou arquivo.

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

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
Janela do 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

Resposta 200:

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

Erros: 400 com a lista de fields quando algum domínio ou campo é inválido (nada é gravado).

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.

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


Os mesmos dados das telas Visão geral, Estatísticas, Incidentes, Grupos e Nodes. Todos exigem dns: ver (1).

Visão geral: grupos com nodes ativos e online, pontuação de saúde, QPS, capacidade estimada, incidentes abertos e avisos.

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

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)
Janela do terminal
curl -H "Authorization: Bearer $V2_TOKEN" \
"https://dns.version2.network/api/pub/v1/dns/stats?range=7d"

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
}

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

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

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.


Exigem rpki: ver (1). Criar CA, publicar ROAs e cadastrar roteadores continuam no painel.

As CAs do cliente (ASN, estágio, avisos da vigilância, estado no Krill) e se o serviço está pronto (ready).

ROAs da CA: prefixos cobertos, ROAs publicadas e as automáticas, anúncios inválidos ou fora da cobertura.

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)”
  1. 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"
  2. Confirme o acesso (repare em scope e levels):

    Janela do terminal
    curl -H "Authorization: Bearer $V2_TOKEN" "$V2_API/whoami"
  3. 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"
  4. 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"
  5. 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"
  6. Exclua o equipamento:

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