Address pools#
2 operations. Roles, error format and pagination are common to the whole API — see the REST API overview.
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:
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.
NetavoBNG Management API v1#
Address pools#
GET /api/v1/address-pools#
List address pools with live utilisation on this appliance.
Description
One row per configured pool, with a row per subnet. used counts committed and offered
blocks (a DHCP OFFER or a PPP negotiation holds its block until it completes or its hold
lapses); quarantined blocks were declined by a DHCP client and return after an hour.
cgnTranslated is true for an IPv4 pool in a VRF bound to on-box CGN — its addresses are
private, never announced, and may be reused on every appliance. Fleet-proxyable.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
[
{
"name": "res-v4",
"family": "ipv4",
"vrf": "internet",
"delegationLength": 32,
"description": "Residential IPv4",
"size": 2044,
"used": 1712,
"free": 332,
"utilisationPercent": 83.8,
"allocationFailures": 0,
"cgnTranslated": false,
"exclude": [
"100.70.0.1"
],
"subnets": [
{
"prefix": "100.70.0.0/22",
"announce": true,
"size": 1023,
"used": 1001,
"free": 22,
"offered": 3,
"quarantined": 0
},
{
"prefix": "100.70.4.0/22",
"announce": true,
"size": 1021,
"used": 711,
"free": 310,
"offered": 0,
"quarantined": 1
}
]
}
]
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/address-pools/{name}/allocations#
List the sessions holding blocks from one address pool.
Description
Ordered by prefix. static marks a statically-assigned address that falls inside the pool
(held so the allocator never hands it out, but not disconnected if its subnet is removed).
Fleet-proxyable.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
limit |
query | 100 | No | Page size (1-1000, default 100). | |
name |
path | string | No | Pool name. | |
offset |
query | 0 | No | Rows to skip. |
Responses
{
"total": 1712,
"offset": 0,
"limit": 100,
"items": [
{
"prefix": "100.70.1.17/32",
"kind": "ipv4",
"sessionId": 40213,
"username": "alice@example.net",
"vrf": "internet",
"static": false
}
]
}
Schema of the response body
{
"required": [
"total",
"offset",
"limit",
"items"
],
"type": "object",
"properties": {
"total": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Allocations in the pool (before paging).",
"format": "int32"
},
"offset": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "The offset this page was taken at.",
"format": "int32"
},
"limit": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "The effective page size.",
"format": "int32"
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AddressPoolAllocation"
},
"description": "The page."
}
},
"description": "A page of an address pool's allocations.",
"example": {
"total": 1712,
"offset": 0,
"limit": 100,
"items": [
{
"prefix": "100.70.1.17/32",
"kind": "ipv4",
"sessionId": 40213,
"username": "alice@example.net",
"vrf": "internet",
"static": false
}
]
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
Schemas#
AddressPool#
| Name | Type | Description |
|---|---|---|
allocationFailures |
Allocations refused because the pool had no free block (since start). | |
cgnTranslated |
boolean | True for an IPv4 pool in a VRF translated by on-box CGN. |
delegationLength |
Prefix length handed to each subscriber (32, 64 or the PD length). | |
description |
string | Free-text description. |
exclude |
Array<string> | Addresses or prefixes never allocated. |
family |
string | ipv4, ipv6-wan or ipv6-pd. |
free |
Blocks available. | |
name |
string | Pool name — the reference AAA returns (Framed-Pool and friends). |
size |
Allocatable blocks on this appliance (excluded addresses not counted). | |
subnets |
Array<AddressPoolSubnet> | The subnets this appliance allocates from, in preference order. |
used |
Blocks held: committed to sessions, on offer, or quarantined. | |
utilisationPercent |
Used as a percentage of size. | |
vrf |
string | null | VRF the pool's addresses live in; null = the default table. |
AddressPoolAllocation#
| Name | Type | Description |
|---|---|---|
kind |
string | ipv4, ipv6-wan or ipv6-pd. |
prefix |
string | The block ("address/32", "prefix/64" or the delegated prefix). |
sessionId |
Holding session. | |
static |
boolean | A static address inside the pool rather than a pool allocation. |
username |
string | null | Subscriber username, when known. |
vrf |
string | null | The session's VRF; null = the default table. |
AddressPoolAllocationsPage#
| Name | Type | Description |
|---|---|---|
items |
Array<AddressPoolAllocation> | The page. |
limit |
The effective page size. | |
offset |
The offset this page was taken at. | |
total |
Allocations in the pool (before paging). |
AddressPoolSubnet#
| Name | Type | Description |
|---|---|---|
announce |
boolean | Announced into BGP as an aggregate. |
free |
Blocks available. | |
offered |
Blocks held by an OFFER or a PPP negotiation not yet committed. | |
prefix |
string | The subnet (CIDR). |
quarantined |
Blocks declined by a DHCP client, out of service for an hour. | |
size |
Allocatable blocks in the subnet. | |
used |
Blocks held (committed, offered or quarantined). |
ProblemDetails#
| Name | Type | Description |
|---|---|---|
detail |
string | null | |
instance |
string | null | |
status |
||
title |
string | null | |
type |
string | null |
Security schemes#
| Name | Type | Scheme | Description |
|---|---|---|---|
| bearerToken | http | bearer | Named API token — the recommended credential for automation. See Authentication in the API overview. |
| sessionCookie | apiKey | Interactive session cookie used by the bundled web UI. Not the integration path for API clients — use a bearer token. See Authentication in the API overview. |
Tags#
| Name | Description |
|---|---|
| Address pools |