Skip to content

Fleet#

Multi-appliance support: the configured appliance list and a read-only proxy to peer appliances.

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:

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.

NetavoBNG Management API v1#

Contact: Netavo

Fleet#

GET /api/v1/fleet/appliances#

List the appliances this appliance knows about.

Description

Always includes this appliance (self: true) followed by the peers configured under webUi.peers. Peer names are the {appliance} key for the proxy endpoint.

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": "lns1-hul1",
        "self": true,
        "url": null
    }
]
Schema of the response body 
{
    "type": "array",
    "items": {
        "$ref": "#/components/schemas/FleetAppliance"
    }
}

{
    "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/fleet/{appliance}/{path}#

Read an API endpoint on a peer appliance (GET-only proxy).

Description

Forwards GET /api/v1/{path} (with the query string) to the named peer using the peer credentials configured under webUi.peers, and relays the peer's status code, body and content type verbatim — so the response schema is that of the proxied endpoint. Only GETs are proxyable; fleet/… (loop) and auth/… (the peer's identity surface) are refused. Example: GET /api/v1/fleet/bng2/sessions/summary.

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.
appliance path string No Peer appliance name from the appliance list.
path path string No The peer-relative API path (everything after `/api/v1/`).

Responses

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

{
    "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#

FleetAppliance#

Name Type Description
name string Appliance name — the `{appliance}` key for the fleet proxy.
self boolean True for the appliance answering this request.
url string | null The peer's base URL (from webUi.peers); null for self.

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
Fleet Multi-appliance support: the configured appliance list and a read-only proxy to peer appliances.