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.

One endpoint refuses the cookie outright: GET /api/v1/metrics, the Prometheus scrape, accepts a bearer token only, so that a scraper can never keep a login session alive.

Roles and authorization

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

Request	Minimum role
Reading accounts, API tokens, sign-in providers or upgrade state: GET /auth/users, /auth/tokens, /auth/providers/…, /system/upgrade	super-user
Reading a subscriber's live CG-NAT translations: GET /sessions/{id}/translations — the one read that names who a subscriber is communicating with	operator
Any other GET/HEAD/OPTIONS	read-only
Your own account: log out, enrol TOTP or a passkey, mint or revoke your own device token	read-only
Operational actions: anything mutating under /sessions (disconnect, CoA, capture) and /diagnostics, POST /system/hardware/refresh, and POST /address-pools/reservations/clear	operator
Writing one CPE GRE circuit: PUT or DELETE /gre-circuits/{id} — the one piece of stored configuration open below super-user, so that a provisioning system can add and remove customer circuits with an operator token. The tunnel listeners (/gre-circuits/listeners/…) are not included	operator
Every other mutation — anything that changes stored configuration, accounts, tokens, certificates, licensing or alarms, and restart or upgrade	super-user

A request below the floor is answered with 403. A mutation is super-user unless the table says otherwise, so an endpoint added later is closed to lower roles until it is listed here.

Reads are open to every role, with secrets withheld: a secret field reads back as a placeholder for everyone. Where the key of a list entry is the secret — an SNMP read-only community — the super-user sees it, because the entry is edited by its key, and other roles see a numbered placeholder.

One part of the configuration is not shown to other roles at all: the accounts (system login) and the sign-in configuration (web-ui auth — API tokens, identity providers, TACACS+, lockout and second-factor policy). GET /config and GET /config/schema omit those paths unless the caller is a super-user, for the same reason GET /auth/users and /auth/tokens are super-user only.

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	4
Alarms	3
Authentication	32	Login/logout, TOTP enrolment, named API tokens, and web/API user management.
CGN	10	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	13	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
IPsec	2
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	2	The Prometheus scrape endpoint, and the time-series history behind the dashboard charts.
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	12	Live subscriber sessions: list/filter, detail with traffic counters, high-resolution live rates, and force-disconnect.
Source VRF Rules	5
System	17	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.

151 operations across 21 sections.