# Cortex xdr

SureCloud connects to Palo Alto Networks Cortex XDR to retrieve endpoint agent status, incident and alert records, and asset telemetry. This allows SureCloud to verify that Cortex XDR agents are deployed and active, that incidents are being detected and triaged, and that the XDR platform is providing continuous coverage across your endpoint estate.

## Authentication and setup

Cortex XDR authenticates API requests using an API key and API key ID. SureCloud uses a read-only Standard API key generated within the Cortex XDR tenant.

{% stepper %}
{% step %}
**Generate an API key in Cortex XDR**

Log in to the Cortex XDR console at [cortex.paloaltonetworks.com](https://cortex.paloaltonetworks.com/). Navigate to **Settings → Configurations → Integrations → API Keys** and click **+ New Key**. Select **Standard** key type and assign the **Viewer** role (read-only). Generate the key and note the **API Key ID**. Copy the **API Key** value — it is only shown once.
{% endstep %}

{% step %}
**Note your tenant ID and FQDN**

Your Cortex XDR tenant FQDN is visible in the console URL (e.g. `api-{fqdn}.xdr.{region}.paloaltonetworks.com`). You will need this as the API base URL in SureCloud.
{% endstep %}

{% step %}
**Enter the credentials in SureCloud**

Navigate to **SureCloud → Integrations → Cortex XDR → Connect**. Enter the API base URL, the **API Key ID**, and the **API Key**. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the API Key securely — it is not shown again after generation. SureCloud encrypts it at rest, but treat it as a sensitive credential. Rotate it every 90 days in **Cortex XDR → Settings → API Keys** and update it in **SureCloud → Integrations → Cortex XDR → Edit Connection**.
{% endhint %}

## Endpoints

Cortex XDR uses a REST API with POST requests. SureCloud uses the following:

| API Call                                             | Use Case                                                                   |
| ---------------------------------------------------- | -------------------------------------------------------------------------- |
| `POST /public_api/v1/endpoints/get_endpoints`        | Enumerate all endpoints including agent status, OS, and last seen time     |
| `POST /public_api/v1/incidents/get_incidents`        | Retrieve incident records including severity, status, and assigned analyst |
| `POST /public_api/v1/alerts/get_alerts_multi_events` | Retrieve alert events associated with incidents                            |
| `POST /public_api/v1/assets/list_assets`             | Retrieve asset inventory data                                              |

## Pagination

All Cortex XDR endpoints use a `request_data` body with `search_from` and `search_to` parameters. SureCloud increments `search_from` by the page size until the returned count falls below the window size.

```json
POST /public_api/v1/endpoints/get_endpoints
{
  "request_data": {
    "search_from": 100,
    "search_to": 200
  }
}
```

## Required permissions

SureCloud requires a Cortex XDR Standard API key with the **Viewer** role, providing read-only access to:

* Endpoint inventory and agent status
* Incidents and alerts
* Asset telemetry

No response action, policy management, or administrative permissions are required.

## Polling frequency

| Data Type                           | Interval       |
| ----------------------------------- | -------------- |
| Endpoint inventory and agent status | Every 24 hours |
| Incidents and severity              | Every 4 hours  |
| Alert events                        | Every 4 hours  |

## Troubleshooting

<details>

<summary>Connection test returns 401 or "auth_failed"</summary>

The API Key ID or API Key is incorrect. Cortex XDR signs requests using both values, and an error in either will cause authentication to fail. Confirm both values are entered correctly in **SureCloud → Integrations → Cortex XDR → Edit Connection**. If the key has been lost, generate a new one in the Cortex XDR console.

</details>

<details>

<summary>Endpoint list returns fewer results than the Cortex XDR console shows</summary>

Cortex XDR may scope endpoint visibility based on the API key's role. Confirm the key was created with the **Viewer** role at the tenant level, not scoped to a specific endpoint group. Check in **Cortex XDR → Settings → API Keys** and verify the key's scope.

</details>

<details>

<summary>Incorrect FQDN causes connection errors</summary>

Each Cortex XDR tenant has a unique FQDN for API access. Using the wrong FQDN will result in DNS errors or 404 responses. Retrieve the correct API URL from **Cortex XDR → Settings → Configurations → Integrations → API Keys** — the FQDN is shown on the API keys page. Update it in **SureCloud → Integrations → Cortex XDR → Edit Connection**.

</details>


---

# Agent Instructions: 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:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/cortex-xdr.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.