Skip to content

Logs#

Recent appliance log entries and a live server-sent-events stream.

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

Logs#

GET /api/v1/logs/stream#

Live log stream (server-sent events).

Description

A text/event-stream response: each new log entry is pushed as an SSE event named log whose data is one JSON object shaped like the tail endpoint's entries. The stream first replays entries newer than sinceSeq (default: only entries after the moment of connection), then stays open; a : keepalive comment is emitted every 15 seconds. Local appliance only — not available through the fleet proxy (poll /logs/tail instead).

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.
sinceSeq query No Replay entries newer than this sequence number before going live.

Responses

Schema of the response body 


{
    "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/logs/tail#

Recent log entries (or entries after a sequence number).

Description

Without sinceSeq, returns the most recent count entries. With sinceSeq, returns up to count entries newer than that sequence number — poll incrementally by echoing the previous response's lastSeq. Entries come from the appliance's in-memory ring buffer (the same events shipped to syslog), so very old entries age out. 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.
count query 100 No Maximum entries to return, clamped to 1–1000 (default 100).
sinceSeq query No Return only entries with a sequence number greater than this.

Responses

{
    "entries": [
        {
            "seq": 184213,
            "timestamp": "2026-08-03T10:24:07.418Z",
            "severity": "notice",
            "msgId": "SESSION_UP",
            "fields": {
                "sessionId": 40213,
                "username": "alice@example.net",
                "vrf": "residential",
                "framedIp": "100.64.12.37"
            }
        }
    ],
    "lastSeq": 184213
}
Schema of the response body 
{
    "required": [
        "entries",
        "lastSeq"
    ],
    "type": "object",
    "properties": {
        "entries": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/LogEntry"
            },
            "description": "The requested log entries, oldest first."
        },
        "lastSeq": {
            "pattern": "^-?(?:0|[1-9]\\d*)$",
            "description": "Sequence number of the newest entry the buffer has seen — pass it as\n            `sinceSeq` on the next poll to fetch only newer entries.",
            "format": "int64"
        }
    },
    "description": "GET /api/v1/logs/tail response.",
    "example": {
        "entries": [
            {
                "seq": 184213,
                "timestamp": "2026-08-03T10:24:07.418Z",
                "severity": "notice",
                "msgId": "SESSION_UP",
                "fields": {
                    "sessionId": 40213,
                    "username": "alice@example.net",
                    "vrf": "residential",
                    "framedIp": "100.64.12.37"
                }
            }
        ],
        "lastSeq": 184213
    }
}

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

LogEntry#

Name Type Description
fields Structured event fields; keys vary by message id.
msgId string Stable machine-readable message id (e.g. "SESSION_UP").
seq Monotonic sequence number within this control-plane process.
severity string Syslog severity name (e.g. "notice", "warning").
timestamp string(date-time) UTC time the event was logged.

LogTail#

Name Type Description
entries Array<LogEntry> The requested log entries, oldest first.
lastSeq Sequence number of the newest entry the buffer has seen — pass it as `sinceSeq` on the next poll to fetch only newer entries.

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
Logs Recent appliance log entries and a live server-sent-events stream.