thakaresandCopilot
2ac6c81dfe
- Prevent 'nx9-wg version' from creating data directories by avoiding database initialization. - Create parent directories when an explicit --database path is provided. - Redact printed generated administrator passwords; announce file path or redact instead. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
86 lines
3.6 KiB
Markdown
86 lines
3.6 KiB
Markdown
# REST API and WebSocket Reference
|
|
|
|
All REST endpoints are nested under the `/api/v1` prefix.
|
|
|
|
---
|
|
|
|
## Authentication
|
|
|
|
The API supports two authentication mechanisms:
|
|
1. **Session Cookie**: `nx9_session=<SESSION_UUID>` (HttpOnly, SameSite=Strict).
|
|
2. **Bearer Token**: `Authorization: Bearer nx9_<TOKEN_BASE64>` (Hashed with SHA-256 on the server).
|
|
|
|
---
|
|
|
|
## Endpoints
|
|
|
|
### 1. Public Endpoints
|
|
- `POST /api/v1/auth/login`: Authenticates administrator with username and password. Sets session cookie.
|
|
- `GET /api/v1/system/health`: Service and database health check.
|
|
- `GET /api/v1/system/version`: Version and build metadata.
|
|
- `GET /api/v1/ws`: WebSocket real-time event stream.
|
|
|
|
### 2. Administrator & Session Management
|
|
- `POST /api/v1/auth/logout`: Invalidates the current session.
|
|
- `GET /api/v1/auth/session`: Returns information about the active session.
|
|
- `POST /api/v1/auth/password`: Changes password and terminates all other sessions.
|
|
- `GET /api/v1/auth/tokens`: Lists all provisioned API tokens.
|
|
- `POST /api/v1/auth/tokens`: Creates a new API token.
|
|
- `DELETE /api/v1/auth/tokens/{id}`: Revokes an API token.
|
|
|
|
### 3. WireGuard Interfaces
|
|
- `GET /api/v1/interfaces`: Lists all interfaces.
|
|
- `POST /api/v1/interfaces`: Creates an interface.
|
|
- `GET /api/v1/interfaces/{id}`: Interface details.
|
|
- `PUT /api/v1/interfaces/{id}`: Updates interface settings.
|
|
- `DELETE /api/v1/interfaces/{id}`: Deletes interface.
|
|
- `POST /api/v1/interfaces/{id}/enable`: Enables interface.
|
|
- `POST /api/v1/interfaces/{id}/disable`: Disables interface.
|
|
- `GET /api/v1/interfaces/{id}/status`: Live statistics, listen port, and connected peer metrics.
|
|
|
|
### 4. WireGuard Peers
|
|
- `GET /api/v1/interfaces/{id}/peers`: Lists peers for a specific interface.
|
|
- `POST /api/v1/interfaces/{id}/peers`: Enrolls a new peer.
|
|
- `GET /api/v1/peers/{id}`: Peer details.
|
|
- `PUT /api/v1/peers/{id}`: Updates peer configuration.
|
|
- `DELETE /api/v1/peers/{id}`: Deletes peer.
|
|
- `POST /api/v1/peers/{id}/enable`: Activates peer.
|
|
- `POST /api/v1/peers/{id}/disable`: Disables peer.
|
|
- `POST /api/v1/peers/{id}/revoke`: Revokes peer.
|
|
- `GET /api/v1/peers/{id}/config`: Downloads standard client `.conf` file.
|
|
- `GET /api/v1/peers/{id}/qr`: Returns SVG, PNG base64, and Data URL QR code representations.
|
|
|
|
### 5. Networks & Routing
|
|
- `GET /api/v1/networks`, `POST /api/v1/networks`, `DELETE /api/v1/networks/{id}`
|
|
- `GET /api/v1/routes`, `POST /api/v1/routes`, `DELETE /api/v1/routes/{id}`
|
|
|
|
### 6. Firewall & nftables
|
|
- `GET /api/v1/firewall/rules`, `POST /api/v1/firewall/rules`, `DELETE /api/v1/firewall/rules/{id}`
|
|
- `POST /api/v1/firewall/rules/{id}/enable`, `POST /api/v1/firewall/rules/{id}/disable`
|
|
|
|
### 7. Audit Log
|
|
- `GET /api/v1/audit`: Paginated and filtered query of security and system events.
|
|
|
|
### 8. Backups
|
|
- `GET /api/v1/backups`: Lists existing backup records.
|
|
- `POST /api/v1/backups/create`: Creates a new snapshot and manifest.
|
|
- `GET /api/v1/backups/{id}/download`: Downloads backup archive.
|
|
- `POST /api/v1/backups/{id}/restore`: Safely restores database.
|
|
- `DELETE /api/v1/backups/{id}`: Deletes backup archive and metadata.
|
|
|
|
### 9. Reconciliation
|
|
- `GET /api/v1/reconcile/plan`: Returns detected drift without making changes.
|
|
- `POST /api/v1/reconcile/apply`: Applies reconciliation plan to live kernel.
|
|
|
|
---
|
|
|
|
## WebSocket Telemetry (`/api/v1/ws`)
|
|
|
|
Upon connection, clients receive a stream of JSON `SystemEvent` frames:
|
|
- `InterfaceChanged { id, action }`
|
|
- `PeerChanged { id, action }`
|
|
- `NetworkChanged { id, action }`
|
|
- `RouteChanged { id, action }`
|
|
- `FirewallChanged { id, action }`
|
|
- `AuditEvent { event_type, message, resource_type, resource_id }`
|