> 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/xdr-5-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)](/xdr-5-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 **Data Broker > Broker Service > View/Edit** 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://cortex-docs.paloaltonetworks.com/xdr-5-api/broker-vm-tenant-side/broker-vm-tenant-overview.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.