Broker VM (On-Appliance) overview

Programmatic management of a single Cortex Broker VM directly from the appliance, served by the broker appliance's on-board web service. These endpoints are reachable on the appliance's HTTPS listener at https://{broker_host}/public_api/v1/... and operate against the local broker only (no tenant orchestration). This API is also referred to as the direct Broker API.

The on-appliance Broker API is available on Broker VM version 32 and later. Ubuntu-based brokers do not support this API.

This surface complements the tenant-side Broker Public API (see the Broker VM (Tenant-Side) API reference), which is served by the Cortex tenant backend and orchestrates brokers remotely. The two surfaces share the /public_api/v1/ prefix but live on different hostnames and use different authentication.

Audiences

1. First-time bootstrap — a fresh broker ships with a factory default admin password. The on-prem operator resets it, generates a 10-minute Bearer token, and uses the token to register the broker against the Cortex tenant.
2. Day-2 on-appliance configuration — install custom SSL or CA certificates, configure NIC / NTP / proxy, reconfigure the internal Docker subnet.
3. Local diagnostics — download a synchronous log bundle from the broker without going through the tenant.

Authentication

Two security schemes are used:

• Admin password — present in the request body for the two bootstrap endpoints (reset initial password, generate token). The broker authenticates by comparing the supplied password to the stored admin password hash.
• Public API token — a short-lived (10-minute TTL) opaque Bearer token issued by the generate-token endpoint. Pass it as Authorization: Bearer <token> to every other endpoint in this spec.

Authorization is the only authentication header used by this on-appliance API. There is no separate key-identifier header (unlike the tenant-side API).

Initial-password gate

Every endpoint except the reset-initial-password endpoint is blocked until the factory password has been changed. Calls to a non-exempt endpoint before that step return 403 Forbidden.

Response envelope

All endpoints follow a single envelope:

• Success (200 OK): { "reply": <payload-or-null> } (reply omitted on endpoints that have no body content).
• Error (4xx / 5xx): { "error": "<message>", "reply": null }.

One endpoint streams application/octet-stream directly instead of the JSON envelope.

Rate limiting

Bootstrap endpoints carry a 5/min/IP cap, and the six on-appliance network-configuration endpoints carry a 1/sec/IP cap. Exceeding the cap returns 429 Too Many Requests. Some endpoints also surface 503 Service Unavailable with a Retry-After header when a prior single-writer operation is still in flight.

Operational warnings

Several network-configuration endpoints are Operationally Dangerous — a bad configuration can leave the appliance unreachable and require console recovery. Treat these as fire-and-poll, not fire-and-expect-immediate-200.