> 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/cortex-cloud-api/broker-vm-tenant-side/broker-vm-tenant-overview.md).

# Broker VM (Tenant-Side) overview

Programmatic management of Cortex Broker VMs from the **Cortex tenant** side. All endpoints are served by the Cortex tenant backend at `https://api-{fqdn}/public_api/v1/brokers/...` and operate on brokers that have already registered with the tenant.

Use this API to:

* List brokers and inspect their configuration, applets, and metrics.
* Edit broker metadata (name, FQDN, proxy, NTP, SSH, SSL, auto-upgrade).
* Issue Broker VM registration tokens for new installations.
* Trigger broker-lifecycle actions (reboot, shutdown, upgrade).
* Configure and (de)activate applets that run on the broker.
* Request, poll, and download remote log bundles.

## Companion specification

A separate **direct** Broker Public API is served by the Broker VM appliance itself at `https://{broker_host}/public_api/v1/...`. It covers initial-bootstrap auth, on-appliance network configuration, and a synchronous log-bundle stream. The two surfaces share the `/public_api/v1/` URL prefix but live on different hostnames and use different authentication. See the [Broker VM (On-Appliance)](/cortex-cloud-api/broker-vm-on-appliance/broker-vm-appliance-overview.md) API reference.

## Authentication

All endpoints in this spec require both:

* `Authorization: <api_key>` — the tenant API key value.
* `x-xdr-auth-id: <api_key_id>` — the tenant API key ID.

Both headers are mandatory; missing either yields `401 Unauthorized`. The authenticated caller must additionally hold the `broker_action` permission, enforced uniformly across every endpoint in this spec.

## Response envelope

All success responses return the resource directly as the response body. All error responses share a single shape:

```json
{ "description": "<message>", "errors": [ { "field": "...", "message": "..." } ] }
```

The `errors` array is present only on validation failures (`400 Bad Request`).

## Rate limiting

Tenant-level rate limiting is enforced by the gateway, not per-operation, and is therefore not represented in this spec.


---

# 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/cortex-cloud-api/broker-vm-tenant-side/broker-vm-tenant-overview.md?ask=<question>&goal=<endgoal>
```

`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.