REST API Overview

Programmatic management interface for AthenaBNG.

Overview

The REST API provides a FastAPI-based HTTP interface for managing AthenaBNG. It runs on HTTPS port 8443 by default and requires JWT authentication for all endpoints except /api/v1/health and /metrics.

Base URL

https://<bng-host>:8443/api/v1

Interactive Documentation

FastAPI auto-generates interactive docs from the endpoint docstrings:

• Swagger UI — https://<bng-host>:8443/api/docs
• ReDoc — https://<bng-host>:8443/api/redoc
• OpenAPI JSON — https://<bng-host>:8443/api/openapi.json

Endpoint Groups

Subscribers

Method	Path	Description
GET	/api/v1/subscribers	List active sessions (filter with ?type=pppoe or ?type=dhcp)
GET	/api/v1/subscribers/summary	Session counts by type
GET	/api/v1/subscribers/{id}	Detailed session information
DELETE	/api/v1/subscribers/{id}	Disconnect a session
PUT	/api/v1/subscribers/{id}/rate	Change session rate (CAKE QoS)
POST	/api/v1/subscribers/disconnect-by-interface	Disconnect all sessions on an interface

System & Configuration

Method	Path	Auth	Description
GET	/api/v1/system/version	any	Version information
GET	/api/v1/system/health	any	Uptime, session count
GET	/api/v1/system/config	any	Running config (secrets redacted)
POST	/api/v1/system/config/set	admin	Set a candidate config value
POST	/api/v1/system/config/delete	admin	Delete a candidate config key
POST	/api/v1/system/config/commit	admin	Commit candidate to running
POST	/api/v1/system/config/rollback	admin	Load archived config as candidate
POST	/api/v1/system/config/discard	admin	Discard candidate changes
GET	/api/v1/system/config/compare	any	Diff running vs candidate

Interfaces

Method	Path	Description
GET	/api/v1/interfaces	All network interfaces
GET	/api/v1/interfaces/vlans	Dynamic VLAN sub-interfaces

QoS

Method	Path	Description
GET	/api/v1/qos	Sessions with CAKE QoS applied
GET	/api/v1/qos/profiles	Available overhead profiles

Routing

Method	Path	Description
GET	/api/v1/routing/bgp/summary	BGP neighbor summary from FRRouting
GET	/api/v1/routing/routes	Kernel routing table

CGNAT

Method	Path	Description
GET	/api/v1/cgnat/sessions	Sessions using CGNAT addresses
GET	/api/v1/cgnat/stats	CGNAT vs public IP counts

Demux

Method	Path	Description
GET	/api/v1/demux/config	Demux configuration
GET	/api/v1/demux/state	Active dynamic VLAN interfaces

Events & Webhooks

Method	Path	Description
GET	/api/v1/events/subscribers	SSE stream of session events
GET	/api/v1/webhooks	List registered webhooks
POST	/api/v1/webhooks	Register a webhook (admin)
DELETE	/api/v1/webhooks/{id}	Delete a webhook (admin)

Monitoring

Method	Path	Description
GET	/metrics	Prometheus metrics (no auth)
GET	/api/v1/health	Health check (no auth)

Response Format

All responses follow a standard envelope:

{
  "status": "ok",
  "data": { ... }
}

Error responses:

{
  "status": "error",
  "message": "description of what went wrong"
}

Authentication

All endpoints except /api/v1/health and /metrics require a JWT bearer token:

# Obtain token
TOKEN=$(curl -sk -X POST https://localhost:8443/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"changeme"}' \
  | jq -r '.access_token')

# Use token
curl -sk -H "Authorization: Bearer $TOKEN" \
  https://localhost:8443/api/v1/subscribers

Configuration

api:
  enabled: true
  listen: "0.0.0.0"
  port: 8443
  tls_cert: "/opt/athena-bng/etc/cert.pem"
  tls_key: "/opt/athena-bng/etc/key.pem"

Next Steps

• Authentication — JWT authentication details
• Endpoints — Full endpoint reference with request/response examples
• Webhooks — Event webhook registration and delivery