> 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-xdr/onboard-cortex-xdr/deployment-steps/manage-api-keys.md).

# Manage API keys

Create, manage, and revoke API keys for Cortex XDR integrations.

API keys are used to manage and secure API interactions. An API key is essentially a unique string of alphanumeric characters that acts as a credential, allowing a specific user or application to access and interact with a particular API. When you request data or perform an action through an API call, you must include this API key in the header. Cortex XDR then verifies the key's authenticity and, if valid, grants the requested access.

### API key visibility and management

API key visibility is determined by your permissions:

* **Account/Instance Administrators and users with Access Management permissions**: You can view all API keys across the tenant.
* **Other users**: You can view only the API keys you have created.

<details>

<summary>How to create an API key</summary>

1. Select **Settings** → **Configurations** → **Integrations** → **API Keys** → **New Key**.
2. In the **Role** tab, perform for the following:
   1. Under **Security Level**, select the type of API Key you want to generate: **Advanced** or **Standard**. The Advanced API key hashes the key using a nonce, a random string, and a timestamp to prevent replay attacks. cURL does not support this but it is suitable with scripts.
   2. Under **Role**, select the desired level of access for this key. You can select from predefined roles or custom roles. Roles are available according to what was defined in either the Cortex Gateway or Cortex XDR Access Management. While administrators can assign any role to an API key, non-administrator users are restricted to roles already assigned to them. You can view the configuration of the role selected by expanding the sections under **Components**. For more information, see [Assign user roles and groups](/cortex-xdr/onboard-cortex-xdr/deployment-steps/set-up-users-and-roles.md#UUID-61ea0230-3be4-e77f-9899-950d47d74fd8).

      <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><h3>Important</h3><p>Ensure the selected role has the appropriate <strong>Credentials</strong> permission. If you select a role where <strong>Credentials</strong> is set to <strong>None</strong>, such as the predefined CLI Role, any API calls made using this key that attempt to fetch, list, create, or modify stored credentials will return a 403 Forbidden error.</p></div>
   3. (Optional) Under **Comment**, provide a comment that describes the purpose of the API key.
   4. (Optional) If you want to define a time limit on the API key authentication, select **Enable Expiration Date**, and select the expiration date and time. You can track the expiration date of each API key in the **API Keys** page. In addition, Cortex XDR displays a API Key Expiration notification in the Notification Center one week and one day prior to the defined expiration date.
3. Review or configure granular scoping for Scope-Based Access Control (SBAC).

   1. **Granular scoping by administrators**: If you are an Account/Instance Administrator permissions, click the **Scope** tab, expand the relevant scoping areas, and define the granular access levels for the API key. The following table explains the options available to configure:

      <div data-gb-custom-block data-tag="hint" data-style="warning" class="hint hint-warning"><h4>Important</h4><p>Before configuring, ensure you review <a href="/cortex-xdr/onboard-cortex-xdr/post-deployment-steps/manage-user-roles-and-access-management/manage-user-scope.md#understand-scoping">Understand scoping</a>.</p></div>
   2. **Automatic scoping for non-administrators**: If you are a non-administrator user (including those with **Access Management** permissions), the API key automatically inherits your existing scope when created or edited. The **Scope** tab is read-only.

   | Scoping Area     | Granular Scoping Configurations                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
   | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | Assets           | <p>Set the <strong>Scope</strong> by selecting one of the following:</p><ul><li><strong>No assets</strong>: No asset is accessible.</li><li><strong>All assets</strong>: Defines access to all assets.</li><li><strong>Select asset groups</strong>: Defines access to the specific assets associated with the Asset Groups selected, and to view all their related cases, issues, and findings for these specific assets and Asset Groups. Under <strong>Select asset groups</strong>, define the specific asset groups that you want to grant access. Only Asset Groups relevant for scoping are listed, which are asset groups that are using only the asset attributes listed in <a href="/cortex-xdr/onboard-cortex-xdr/post-deployment-steps/manage-user-roles-and-access-management/manage-user-scope.md#understand-scoping">Manage user scope</a> (under <strong>Understand scoping</strong> → <strong>Scoping Areas</strong> → <strong>Assets</strong>).</li></ul><p>The scoping of assets also affects the scoping of cases, issues, and findings.</p><p>Visibility of a case or issue is determined by the presence of associated entities. If a case or issue is associated with only an asset OR only an endpoint agent, it is visible only if that specific entity is within the user's scope and the domain is in scope. If a case or issue is associated with both an asset AND an endpoint agent, it is visible if either the asset OR the endpoint agent is within the user's scope and the domain is in scope.If a case or issue has no associated asset or endpoint agent, visibility depends on the domain scope and the <strong>Allow access to cases and issues that are not referencing known assets or endpoints</strong> setting.</p><div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><p><strong>Note</strong></p><p>Visibility of Security domain Issues that refer to assets with agents is controlled by the <strong>Endpoints</strong> scoping configuration.</p></div>                                                                                                                                                                                                                                                                                            |
   | Cases and Issues | <p>Set the <strong>Scope</strong> by selecting one of the following:</p><ul><li><strong>No cases and issues</strong>: Defines access to no cases and issues.</li><li><strong>All cases and issues</strong>: Defines access to all cases and issues. Users can view cases or issues where either the referenced asset OR endpoint agent is in scope. Use the <strong>Assets</strong> and <strong>Endpoints</strong> sections to define which entities are in scope.</li><li><p><strong>Select domains</strong>: Defines access to the domains selected to view their related cases and issues. Under <strong>Select domains</strong>, define the specific domains that you want to grant access.</p><p>Users can only view cases or issues that belong to a domain for which the user has a scope, and where either the referenced asset or endpoint agent is within their scope. Use the <strong>Assets</strong>, <strong>Endpoints</strong>, and <strong>Cases and Issues</strong> (Select domains) sections to define which entities and domains are in scope.</p></li></ul><p>When selecting <strong>All cases and issues</strong> or <strong>Select domains</strong>, you can separately configure access to issues and cases that lack an asset reference or where the referenced asset is not in <strong>All Assets</strong> and <strong>All Endpoints</strong> inventories. To provide access, select the <strong>Allow access to cases and issues that are not referencing known assets or endpoints</strong> checkbox. Once selected, you can specifically control which users have access to issues and cases that lack <strong>Affected Assets</strong> (as seen in the issue’s panel) and <strong>Assets</strong> (as seen in the case's panel), or where the listed assets are not part of the Asset or Endpoint inventories. When the assets listed are not part of the inventories, the asset string is typically non-clickable. In some cases, such as for identity-related issues, assets may open a dedicated <strong>User Risk View</strong>, which differs from the standard inventories panels. In the <strong>Issues</strong> and <strong>Cases</strong> tables, such items can be identified by empty values in the following columns: Asset IDs, Target Agent Identifier, and Source Agent Identifier.</p> |
   | Endpoints        | <p>Set the <strong>Scope</strong> by selecting one of the following:</p><ul><li><p><strong>No endpoints</strong>: Defines access to no endpoints with no ability to view their related agent management and enterprise policies.<br>Visibility of a case or issue is determined by the presence of associated entities:</p><ul><li>If a case or issue is associated with only an endpoint agent OR only an asset, it is visible only if that specific entity is within the user's scope and the domain is in scope.</li><li>If a case or issue is associated with both an endpoint agent AND an asset, it is visible if either the endpoint agent OR the asset is within the user's scope and the domain is in scope.</li><li>If a case or issue has no associated endpoint agent or asset, visibility depends on the domain scope and the <strong>Allow access to cases and issues that are not referencing known assets or endpoints</strong> setting.</li></ul></li><li><strong>All endpoints</strong>: Defines access to all endpoints with the ability to view their related agent management and enterprise policies. This configuration can impact the visibility of related <strong>Security</strong> domain <strong>Cases and Issues</strong>, but will not affect asset visibility.</li><li><strong>Select specific (at least one required)</strong>: Defines specific access to all endpoint groups by selecting <strong>Endpoint Groups</strong> or all endpoint tags by selecting <strong>Endpoint Tags</strong> to view their related agent management and enterprise policies. This configuration can impact the visibility of related <strong>Security</strong> domain <strong>Cases and Issues</strong>, but will not affect asset visibility.</li></ul>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><h3>Important</h3><p>By default, <strong>Enable Scope Based Access Control</strong> is disabled in Settings → Configurations → General → <strong>Server Settings</strong>, and granular scoping is not enforced. Before enabling SBAC, we recommend that an administrator or a user with <strong>Access Management</strong> permissions first ensures that the users, user groups, and API Keys defined in Cortex XDR are granted the required access by assigning the relevant scopes. For more information, see <a href="/cortex-xdr/onboard-cortex-xdr/post-deployment-steps/manage-user-roles-and-access-management/manage-user-scope.md#understand-scoping">Manage user scope</a>.</p></div>
4. Click **Generate** to generate the API key.
5. Copy the generated API key and click **Done**.

   <div data-gb-custom-block data-tag="hint" data-style="info" class="hint hint-info"><h3>Important</h3><p>You will not be able to view the API key again after you complete this step. Ensure that you copy the API key before closing the notification.</p></div>

</details>

<details>

<summary>Actions available on API Keys</summary>

Below are some of the main pivot (right-click) options for actions available on each API key listed in the API Keys table. Only tasks that need further explanation are explained below.

| Action                                   | Description                                                                                                                                                                                                                                   |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| View Examples                            | Copies the Python 3 example, so you can edit it to set up your own API calls.                                                                                                                                                                 |
| Copy text to clipboard / Copy entire row | Copies the value of an API setting, such as the ID, to the clipboard by right-clicking the setting and selecting **Copy text to clipboard**. You can copy all the settings of an API key by right-clicking and selecting **Copy entire row**. |
| Filter API keys                          | Filters the API keys by selecting one of the filter options, such as **Show rows 30 days prior to...**. You can then adjust the filter options to filter the API keys according to all the available fields.                                  |

</details>

<details>

<summary>API enforcement for credentials</summary>

If an API key is assigned a role with **Credentials** set to **None**:

* **Data access**: `GET` or `List` calls to credential endpoints will fail.
* **Modification**: `POST`, `PUT`, or `DELETE` calls to create or update credentials will fail.
* **Automation**: Any scripts or external integrations using this API key to retrieve secrets from the credential store will return an unauthorized error.

</details>


---

# 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/cortex-xdr/onboard-cortex-xdr/deployment-steps/manage-api-keys.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.