Skip to main content

API Authentication

JWT-based authentication for the REST API.

Overview​

The REST API uses JWT (JSON Web Tokens) for authentication. All requests (except /api/v1/health and /metrics) must include a valid JWT bearer token in the Authorization header.

Roles​

AthenaBNG has two API user roles:

  • admin — Full access. Can modify configuration, disconnect sessions, register webhooks.
  • operator — Read-only access. Can view subscribers, interfaces, routing, QoS, and system status. Cannot modify configuration or disconnect sessions.

Getting a Token​

POST /api/v1/auth/login

Request:

curl -sk -X POST https://localhost:8443/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "changeme"}'

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}

Using the Token​

Include the token in the Authorization header of every request:

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

Scripted Usage​

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')

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

Token Expiry​

Tokens expire after 1 hour by default. When a token expires, request a new one using the login endpoint.

User Management​

API users are defined in the BNG configuration file under the api.users section:

api:
  enabled: true
  users:
    - username: admin
      password_hash: "$2b$12$..."
      role: admin
    - username: operator
      password_hash: "$2b$12$..."
      role: operator

Password hashes are bcrypt. Generate one with:

python3 -c "import bcrypt; print(bcrypt.hashpw(b'yourpassword', bcrypt.gensalt()).decode())"

JWT Secret​

The JWT signing secret is read from the ABNG_API_SECRET environment variable. If not set, a random secret is generated at startup (tokens will not survive API restarts).

For production, set a persistent secret in the systemd unit:

# /etc/systemd/system/abng-api.service.d/override.conf
[Service]
Environment=ABNG_API_SECRET=your-long-random-secret-here

Security Best Practices​

  1. HTTPS Only — Always use TLS (port 8443)
  2. Strong Passwords — Use strong, unique passwords for API users
  3. Persistent Secret — Set ABNG_API_SECRET in production
  4. Network Restriction — Bind API to management interface or use firewall rules
  5. Token Rotation — Request new tokens regularly; do not cache indefinitely

Troubleshooting​

401 Unauthorized​

{"detail": "Could not validate credentials"}

Causes:

  • Missing Authorization header
  • Malformed token
  • Expired token
  • Invalid JWT secret (API restarted without persistent ABNG_API_SECRET)

Solution: Request a new token via /api/v1/auth/login.

403 Forbidden​

{"detail": "Admin role required"}

Cause: The authenticated user has operator role but the endpoint requires admin.

Solution: Log in with an admin user.

Next Steps​