> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt > Use this file to discover all available pages before exploring further. # Cortex XDR > Connect Cortex XDR so agents can triage incidents, alerts, and endpoints, and update incidents through your Approvals Connect Palo Alto Networks Cortex XDR and CloudThinker agents can review incidents with their alerts and artifacts, search alerts, check endpoint status, and assign, reprioritize, or resolve incidents through your [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md). The connection uses a Cortex XDR **API key** and its **API key ID**. > [!NOTE] > > Cortex XDR is available on [self-hosted deployments](https://docs.cloudthinker.io/guide/deployment/overview.md) of CloudThinker. To use it on CloudThinker Cloud, [contact us](https://cloudthinker.io/contact). ## Prerequisites * A Cortex XDR user who can create API keys. Palo Alto lets administrators give a key any role, and other users only a role they already hold. * The **Admin** role in your CloudThinker workspace, which can add and edit connections. See [Roles](https://docs.cloudthinker.io/guide/security/roles.md). ## Setup **1. Create an API key** In Cortex XDR, go to **Settings → Configurations → Integrations → API Keys** and click **New Key**. On the **Role** tab: * **Security Level**: **Advanced**. It hashes the key with a random nonce and a timestamp, which blocks replayed requests. **Standard** also works. * **Role**: **Viewer** for read-only access. For incident changes, pick a role that can triage cases, such as **Investigator**. See [Required permissions](#required-permissions). * **Comment**: optional, for example `CloudThinker`. * **Enable Expiration Date**: optional. Cortex XDR warns you in the Notification Center one week and one day before the key expires. Click **Generate**, copy the key, and click **Done**. Cortex XDR shows the key only once. **2. Copy the key ID and the API URL** In the **API Keys** table, note the number in the key's **ID** column. Click **Copy API URL**. The API address is `https://api-` followed by your tenant's FQDN, with no path. **3. Add the connection in CloudThinker** In the sidebar, click **More → Workspace settings → Connections**. On the **Builtin Connections** tab, search for **Cortex XDR** and click **Connect**. Fill in the fields from [Connection details](#connection-details) and click **Connect**. CloudThinker tests the key by reading your incident count. **Success state:** the message reads `Cortex XDR connected; the key reads incidents.` and the connection shows **Connected**. ## Connection details | Field | Description | Example | | - | - | - | | **API URL** | Your tenant's API address, from **Copy API URL**. It starts with `https://api-` and has no path | `https://api-` | | **API key ID** | The number in the key's **ID** column | `12` | | **API key** | The key you copied when you generated it | `` | | **Key security level** | **Advanced** (default) or **Standard**. Match the **Security Level** you picked for the key | **Advanced** | ## Required permissions The key can do exactly what its role allows. | Goal | Role on the key | | - | - | | Read incidents, alerts, and endpoints | **Viewer**, Palo Alto's read-only role | | Also change an incident's status, severity, or assignee | A role that can triage cases, such as **Investigator** | Before you click **Generate**, expand the sections under **Components** to see what the selected role can do. Check that it can view incidents (cases), alerts (issues), and endpoints. If **Scope Based Access Control** is on in your tenant, the key also needs a scope. Agents only see incidents, alerts, and endpoints inside it. > [!TIP] > > Start with **Viewer**. Create a second key with a triage role only when you want agents to update incidents. ## Agent capabilities | Capability | What agents can do | Approval | | - | - | - | | **Overview** | Summarize new and under-investigation incidents, high and critical alerts from the last 24 hours, and isolated, disconnected, or lost endpoints | Runs without asking | | **Incidents** | List open incidents, or incidents by status, over up to 365 days. Open one incident with its alerts and its network and file artifacts | Runs without asking | | **Alerts** | Search alerts by time window (up to 30 days), severity, source, or alert ID | Runs without asking | | **Endpoints** | Look up endpoints by host name, IP address, endpoint ID, status, or isolation | Runs without asking | | **Incident changes** | Change one incident's status, severity, or assignee, and add a comment when resolving it | Each change | Lists return at most 100 rows and always report the true total. Cortex XDR 6 calls incidents *cases* and alerts *issues*. Palo Alto keeps the incident and alert APIs working after the upgrade, so the connection works on both. Before a change, the agent names the incident, its current status, severity, and assignee, and the change it wants to make. After it, the agent reads the incident back, reports whether the change took effect, and can set the earlier values back. Agents can't isolate endpoints, run scripts, retrieve or quarantine files, edit allow and block lists, or run XQL queries. Do those in the Cortex XDR console. Writes also need **Allow writes** on, which starts on. To keep the connection read-only in CloudThinker, open **Cortex XDR** in **More → Workspace settings → Connections** and turn off **Allow writes**. Every change an agent makes goes through your workspace's [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md) first. On the default **Auto · Rules + AI · Ask me** mode, AI judgment can let a safe change run without asking — and an Allow Rule can too, once CloudThinker turns on [Rule enforcement](https://docs.cloudthinker.io/guide/approvals/rules.md#troubleshooting) for your workspace. Choose **Manual** to approve every change yourself. ### Verify the connection ```text theme={null} Summarize my Cortex XDR: new and under-investigation incidents, high and critical alerts from the last 24 hours, and endpoints that are isolated, disconnected, or lost ``` **Expected result:** incident and alert totals with their newest rows, and endpoint counts by state. ### Example prompts ```text theme={null} Which Cortex XDR incidents are new or under investigation, and which hosts and users do they involve? Open Cortex XDR incident 1234 and summarize what happened, with its alerts and artifacts Assign Cortex XDR incident 1234 to me and set its severity to high ``` Replace `1234` with an incident ID from Cortex XDR. ## Troubleshooting The accordion titles below are the exact messages CloudThinker shows when the connection test fails. > [accordion] Cortex XDR rejected the API key. Check the key ID and the key, and that the key has not expired. > > Check that **API key ID** holds the number from the **ID** column, not the key, and that you pasted the whole key. In **Settings → Configurations → Integrations → API Keys**, check the key's **Expiration Time**. A key you can't see again can't be recovered: generate a new one. > [accordion] This is a Standard key. Edit the connection and set Key security level to Standard. > > **Key security level** doesn't match the key. Set it to the level the message names. The same applies the other way round for an Advanced key. > [accordion] The API key works, but its role cannot read incidents. Give the key the Viewer role or higher. > > The key signed in, but its role can't view incidents. Edit the key's role in Cortex XDR, or generate a new key with **Viewer**, and connect again. > [accordion] That is the console address. Use the API URL from Settings > Configurations > API Keys > Copy API URL; it starts with [https://api-](https://api-). > > You entered the address you sign in to. In current Cortex XDR, the button is under **Settings → Configurations → Integrations → API Keys**. Use **Copy API URL**, which gives the address that starts with `https://api-`. > [accordion] That address answered, but not as the Cortex XDR API. Use the API URL, which starts with [https://api-](https://api-). > > The address isn't your tenant's API. Use the value from **Copy API URL**. The same fix applies to `Cortex XDR answered with a redirect. Use the exact API URL, with no path.` > [accordion] This Cortex XDR tenant has no license for the public API. > > Cortex XDR refused the call because of your license. Palo Alto lists the license each API needs in its [API reference](https://cortex-docs.paloaltonetworks.com/xdr-api/understand-cortex-xdr-licenses). > [accordion] Cortex XDR is rate-limiting this key. Try again in a minute. > > Cortex XDR allows 10 API requests per second per tenant, shared by every API key on it. Wait a minute and connect again. > [accordion] An agent says the Cortex XDR write tool is off on this connection > > **Allow writes** is off. Turn it on in **More → Workspace settings → Connections** if you want agents to update incidents, then ask again. If the change then fails with HTTP 403, the key's role can't triage cases. ## Security * **Least privilege** — grant only the permissions the agents need for your use case; start read-only and widen later. * **Read-only by default** — use read-only credentials unless you want agents to make changes through this connection. * **Rotate credentials** — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection. * **Revoke on offboarding** — remove the credential at the provider when you delete a connection or a teammate leaves. - **Use an Advanced key with an expiration date.** An Advanced key blocks replayed requests, and an expiration date limits how long a leaked key works. - **Use a dedicated key.** Create the key only for CloudThinker, so you can revoke it without affecting other integrations. - **Key stays on your API address.** CloudThinker sends the key only to the **API URL** you enter and never follows a redirect elsewhere. ## Related > [card] [Approvals](https://docs.cloudthinker.io/guide/approvals/overview.md) > > Decide which incident changes run, wait for a person, or are refused > [card] [Wazuh Connection](https://docs.cloudthinker.io/guide/connections/wazuh.md) > > Security alerts and agent health from your Wazuh SIEM This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.