> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xsiam-api/broker-vm-on-appliance/broker-vm-appliance-overview.md). # 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. {% hint style="info" %} The on-appliance Broker API is available on Broker VM version 32 and later. Ubuntu-based brokers do not support this API. {% endhint %} This surface complements the **tenant-side** Broker Public API (see the [Broker VM (Tenant-Side)](/xsiam-api/broker-vm-tenant-side/broker-vm-tenant-overview.md) 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 ` 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": }` (`reply` omitted on endpoints that have no body content). * **Error (4xx / 5xx):** `{ "error": "", "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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/xsiam-api/broker-vm-on-appliance/broker-vm-appliance-overview.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.