RustProxy/docs/API.md

Administration API and configuration automation

RustProxy exposes an authenticated administration API on the separate administration listener (normally 127.0.0.1:9090). Open /docs → API after signing in to view the bundled OpenAPI/Swagger schema, including request bodies and available actions. That schema is the endpoint reference; server validation remains authoritative.

Selected API endpoints

The current bundled src/admin/openapi.json declares these operations (among others):

Method and path	Purpose
GET /healthz	Minimal health response, without privileged state.
GET /api/auth/status	Whether first-time administrator setup is required.
POST /api/auth/login · POST /api/auth/logout	Start/end a browser admin session.
GET /api/auth/session	Validate current admin session.
GET /api/config · PUT /api/config	Read or replace validated, revisioned configuration. GET also returns read-only storage metadata (SQLite/JSON source and paths).
POST /api/config/reload	Revalidate and hot-reload manually changed --config JSON; revision-aware.
GET/POST /api/api-tokens · DELETE /api/api-tokens/{id}	List/generate/revoke general RO/RW API tokens (browser-admin-only).
GET/POST/DELETE /api/prometheus-token	Inspect/generate/rotate/revoke a standalone Prometheus scrape token (browser-admin-only).
PUT /api/config/{section}	Update one supported configuration section.
GET /api/config/history · POST /api/config/history/restore	Review/restore retained configuration snapshots.
GET /api/status · GET /api/backends	Operational status and backend observations.
GET /api/cache · POST /api/cache/purge · POST /api/cache/invalidate	Cache observations and authenticated invalidation.
GET /api/logs · GET /api/live-logs	Recent and streaming request logs.
GET /api/file-logs · GET /api/file-logs/query	Stored-log exploration.
GET /api/traffic · GET /api/system-info	Traffic and system observations.
GET /api/docker · POST /api/docker/refresh	Docker-agent observation and refresh.
GET /api/certificates · POST /api/certificates/upload	Certificate inventory/import.
GET /api/acme · POST /api/acme/issue · POST /api/acme/renew	Managed certificate jobs.
GET/PUT /api/preferences	Personal UI settings.
GET /api/dashboard-presets and named preset operations	Saved Overview presets.
GET /docs/openapi.json	Protected machine-readable API specification.

Some paths have additional DELETE/PATCH operations, job-status resources, query parameters or restricted actions. Use OpenAPI for the actual fields/methods, not guesses based on a table. GET /metrics here is not a replacement for the separate Prometheus exporter.

Authentication and safe writes

• Ordinary API calls require an administrator browser/session cookie on the admin listener, or a scoped general API Bearer token for explicitly allowlisted API methods/paths. Logging in also provides CSRF context. Writes require correct Host/Origin, X-CSRF-Token and X-RustProxy-Request: 1 as enforced by the server.
• The Swagger API tab uses the signed-in session. Read calls can be executed; mutations require explicit confirmation. It cannot bypass server-side authorization.
• Configuration writes are revisioned (expected_revision) and rejected if based on a stale save. GET /api/config returns {revision, config, storage}; storage is runtime metadata and must not be copied inside the editable config object or included as a write parameter. PUT and history-restore responses remain {revision, config}. Prefer section updates over replacing the entire document when practical.
• /docs, API schemas, configuration, logs, certificates and most observations are not anonymous. Keep the listener restricted and use HTTPS or a tunnel for remote access.

Local CLI alternatives

The included rust-proxy program supports configuration and backup operations without turning browser sessions into automation tokens:

rust-proxy --data-dir /var/lib/rustproxy config get
rust-proxy --data-dir /var/lib/rustproxy config validate config.json
rust-proxy --data-dir /var/lib/rustproxy config apply config.json
rust-proxy --data-dir /var/lib/rustproxy config reload
rust-proxy --data-dir /var/lib/rustproxy backup create --output /private/site.rpb

Run CLI commands as an authorized local operator with the correct private data directory. The admin subcommands provide first setup, password recovery, session revocation and status; tls supports certificate generate/import/deploy/reload. Run rust-proxy --help for exact options.

Restricted Certificate API credentials

Settings → Certificate API can create credentials containing a Key ID + Bearer token with explicit certificate-ID grants. New keys default to reload-only; deploy permission is separate. The clear token is displayed at creation/rotation and is not a general admin API token.

An authorized client sends:

Authorization: Bearer <secret>
X-RustProxy-Certificate-Key: <key-id>

The credential can be used only for allowed certificate reload/deploy operations, not configuration, users, metrics or secret management. Non-loopback use requires the appropriate administration HTTPS security boundary. Rotate broad or legacy credentials. See API access and Certificates.