Skip to content

REST API#

The appliance exposes a versioned management API under /api/v1. These pages are rendered at build time from the product's own OpenAPI document — the same one the running appliance serves at /api/v1/openapi/v1.json, with an interactive reference at /api/v1/docs.

Machine-readable spec

The complete document is included in the site as openapi.json — point a client generator at that rather than scraping these pages. Each section below also has its own pruned document.

The management REST API for a NetavoBNG appliance — the same API the bundled web UI is built on. Use it to observe and operate the appliance: subscriber sessions, routing, CG-NAT, L2TP tunnels, logs, metrics, configuration, and licensing.

Base URL and TLS#

The API is served over HTTPS by the appliance's web listeners (webUi.listeners, default https://127.0.0.1:8443). A factory appliance presents a self-signed certificate until an operator uploads one (POST /api/v1/config/webui/certificate) or enables ACME. All paths below are relative to the listener root, e.g. https://bng1.example.net:8443/api/v1/sessions.

Authentication#

Use a named bearer token. Every endpoint except POST /api/v1/auth/login, POST /api/v1/auth/enrol and GET /api/v1/system/health requires one. A super-user creates a token with POST /api/v1/auth/tokens; the plaintext (bngtok_…) is returned exactly once at creation and only a SHA-256 hash is stored on the appliance, so a lost token is replaced rather than recovered. Send it on every request:

Authorization: Bearer bngtok_…

Each token carries a fixed role (read-only, operator or super-user) and is exempt from CSRF checks. This is the single credential you need for scripts, integrations and monitoring.

Accounts and tokens share one identity model with the appliance CLI (login.users). Repeated authentication failures lock the account/source-IP pair out temporarily (HTTP 423 on login).

Session cookies (bundled web UI only)#

The appliance also accepts an interactive session cookie, which is how the bundled web UI authenticates. It is documented for completeness — API clients should not use it. It is bound to a login session and obliges the caller to manage a CSRF token, neither of which suits automation.

POST /api/v1/auth/login with username + password (and a TOTP code when enrolled) sets the bng_session cookie and returns a csrfToken (also available from GET /api/v1/auth/whoami). Cookie-authenticated mutating requests (anything other than GET/HEAD/OPTIONS) must also send that value in the X-CSRF-Token header or they are rejected with 403.

Roles and authorization#

Each user/token carries one role; every request is checked against a role floor:

Request Minimum role
Any GET/HEAD/OPTIONS read-only
Most mutations (e.g. disconnect a session) operator
Mutations under /auth, /config, /vrfs, /routing/config, /cgn super-user

A request below the floor is answered with 403. Per-endpoint docs note the effective floor where it isn't obvious from the table.

Errors#

Errors use RFC 9457 problem details (application/problem+json) with title, status and a human-readable detail, e.g.:

{ "type": "about:blank", "title": "Session not found", "status": 404, "detail": "No active session 42." }

Conventions#

  • Pagination — list endpoints take offset/limit query parameters and return total, offset and the page of items, so clients can page deterministically.
  • Timestamps are UTC, ISO 8601. Rates are bits/second (…Bps) or packets/second (…Pps).
  • Live streaming — GET /api/v1/logs/stream is a server-sent-events (text/event-stream) endpoint; everything else is JSON.
  • Fleet proxying — on multi-appliance deployments, GET endpoints can be read on a peer via GET /api/v1/fleet/{appliance}/{path}. Mutations are always local to the appliance.
  • Configuration commits — config-changing endpoints run the CLI's candidate → validate → commit pipeline. They return 422 when validation rejects the change, and restartRequired hints when a commit only takes full effect after a restart.

Interactive documentation#

This document is served at /api/v1/openapi/v1.json; an interactive reference UI (browse, generate client snippets, try requests) is at /api/v1/docs. Both require authentication, like the rest of the API.

Sections#

Section Operations Description
Address pools 2
Alarms 3
Authentication 32 Login/logout, TOTP enrolment, named API tokens, and web/API user management.
CGN 9 Carrier-grade NAT (NAT44): status, IP groups (public pools), live bindings, and binding identity enrichment.
Captures 3 Per-session packet captures: start/stop a GRE mirror to a remote collector and list active captures.
Configuration 8 Schema-driven appliance configuration: read, validate, commit, history, and rollback — the same candidate/commit pipeline as the CLI.
Fleet 2 Multi-appliance support: the configured appliance list and a read-only proxy to peer appliances.
GRE Circuits 8
L2TP 2 Live L2TP tunnels — downstream (from LACs, terminated on this LNS) and upstream (to wholesale LNSes).
Licensing 5 Licence status, telemetry preview, activation, renewal, and offline licence install.
LocalSubscribers 10
Logs 2 Recent appliance log entries and a live server-sent-events stream.
Metrics 1 Time-series metrics for dashboards: session counts and per-port throughput.
RADIUS 1 RADIUS server pool health: live/dead state and per-server counters.
Routing 11 Live BGP and IGP (IS-IS or OSPF) status, per-VRF and per-neighbor route tables, and the editable BGP/routing configuration.
Sessions 5 Live subscriber sessions: list/filter, detail with traffic counters, high-resolution live rates, and force-disconnect.
Source VRF Rules 5
System 9 Appliance health, status, hardware inventory, and network interface table.
SystemUpgrade 3
VRFs 4 Configured VRFs merged with live per-VRF session counts, plus VRF create/edit/delete.

125 operations across 20 sections.