Operator HTTP API

portunus-server exposes its operator surface as an HTTP API on operator_http_listen (loopback by default). Most /v1/* requests require either a Web session cookie or an API bearer token.

Authentication

Web UI users authenticate through local password login:

POST /v1/auth/login
Host: 127.0.0.1:7080
Content-Type: application/json

{"user_id":"admin","password":"correct horse battery staple"}

Successful login returns {"password_change_required": false} and sets an HttpOnly portunus_session cookie. API clients and CLI automation continue to use bearer credentials:

GET /v1/clients
Host: 127.0.0.1:7080
Authorization: Bearer T006-quickstart-token

Cookie-authenticated mutating requests (POST, PUT, PATCH, DELETE) must include an exact same-origin Origin header, X-Portunus-CSRF: 1, and JSON content type when a body is present. Bearer-token requests do not need the CSRF header.

Responses on missing / invalid authentication:

Endpoints by area

Auth

Self

Clients

Client-scoped routes address the client by its stable client_id (a ULID assigned at enrollment). client_name is a free-form display label and is not an identifier — duplicates are allowed and a rename leaves the id intact. An unknown or malformed client_id returns 404 on every client-scoped route (it never reveals whether a colliding name exists).

Rules

Users

Credentials

Grants

Rate limiting (v0.11+)

Per-rule caps travel on the POST / PUT /v1/rules body (see rate_limit above). The endpoints below set a per-(owner, client) envelope.

Traffic quotas (v0.13+)

Per-(user, client) monthly traffic quotas and historical traffic queries. Traffic queries take from and to (Unix seconds, required) plus an optional bucket (sample granularity).

Settings (v0.14+)

Audit (v0.6+)

Metrics (v0.6+)

The standalone scraper-facing endpoint at metrics_listen:7081/metrics is unchanged (Prometheus continues scraping without bearer).

Request bodies for the common write endpoints

The JSON shapes most automation needs. Unlisted fields are optional.

POST /v1/auth/onboarding

First-admin creation while no active superadmin exists. Requires the setup token printed in the server logs.

{
  "user_id": "admin",
  "display_name": "Admin",
  "password": "correct horse battery staple",
  "password_confirm": "correct horse battery staple",
  "setup_token": "<token from server logs>"
}

Returns 201 with { user_id, display_name, role }. It does not set a session cookie — call POST /v1/auth/login next before any authenticated request.

POST /v1/auth/login

{ "user_id": "admin", "password": "correct horse battery staple" }

Returns 200 { "password_change_required": false } and sets the HttpOnly portunus_session cookie used by subsequent cookie-authenticated calls.

POST /v1/client-enrollments

{ "name": "edge-01", "address": "edge-01.example.com", "ttl_secs": 600 }

• name — the client name to enroll.
• address — the public host consumers of this client's forwarded ports will reach. It must be a bare host (DNS name or IP) without a port; a host:port value is rejected with 400 invalid_client_address.
• ttl_secs — optional code lifetime (defaults to the server's setting).

Returns { client_name, expires_at, command, uri }. Run the command (or redeem uri) on the edge host. The server endpoint embedded in the URI comes from the advertised endpoint, falling back to 127.0.0.1:7443.

POST /v1/users/{id}/credentials

{ "label": "ops-cli" }

Returns 201 { credential_id, user_id, token, label, created_at }. The token is the bearer credential and is shown once — store it immediately.

Status code semantics

The full code → exit-code → HTTP-status mapping is frozen at v1; see the per-spec contract docs in specs/*/contracts/operator-api.md.

Example: push a rule with caps

curl -sS -X POST http://127.0.0.1:7080/v1/rules \
  -H "Authorization: Bearer $PORTUNUS_OPERATOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "client": "edge-01",
    "listen_port": 8443,
    "targets": [
      {"host": "primary.local", "port": 443, "priority": 1},
      {"host": "backup.local",  "port": 443, "priority": 2}
    ],
    "protocol": "tcp",
    "sni_pattern": "*.example.com",
    "rate_limit": {
      "bandwidth_in_bps": 1048576,
      "concurrent_connections": 1000
    }
  }'