> 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-xsiam/configure-cortex-xsiam/multi-tenant/child-tenant-management/pairing-accesss-control/manage-the-pairing-api-key.md).

# Manage the pairing API key

Learn to manage pairing access control and configure API key permissions and data scope in Cortex XSIAM.

When a main tenant and a child tenant are paired, a new pairing API key with a **Pairing Key** role is created on the child tenant. You can change the role and edit the scope of the API key.

{% hint style="info" %}
**NOTE**

* Pairing access control is not enabled by default; contact Customer Support to enable it for your tenant.
* The Pairing Key role is only assigned to newly generated pairing keys after the feature is enabled.
  {% endhint %}

### Prerequisites

* Verify that you are an Instance Administrator or Account Admin for the child tenant.
* Verify that your tenant has an active pairing. Go to **Settings > Configuration > Tenant Management** and confirm that a parent tenant appears with a **Paired** status. Pairing access control only affects the pairing API key created when a parent tenant pairs with your tenant.

### Edit the API key access scope

1. Go to **Settings > Configuration > API Keys**.
2. Locate the pairing key, identified by its system-generated comment and **System** security level.
3. Right click to **Edit** the key.
4. Update the key's Scope-Based Access Control (SBAC) scope to restrict which assets, cases and issues, and dataset rows the parent tenant can access.

### Change the assigned role for the API key

{% hint style="info" %}
**NOTE**

The default Pairing Key role includes all recommended permissions for standard operation. If you assign a role with fewer permissions, the parent tenant may be unable to view certain child tenant data or execute specific management actions.
{% endhint %}

You can change the role assigned to the API pairing key. The default **Pairing Key** role is a system role and cannot be edited. You can duplicate the Pairing Key role, edit the permissions for the duplicated role, and then update the role in the API key settings. You can also assign any existing role to the API key. To change the assigned role:

1. Go to **Settings > Configuration > API Keys**.
2. Locate the pairing key, identified by its system-generated comment and **System** security level.
3. Right click to **Edit** the key.
4. In the **Roles** field, select a different role.
5. Save your changes.

### Troubleshooting

| **Problem**                                                                               | **Likely Cause**                                                                                                                                                                                                        | **What to Do**                                                                                                                                                                |
| ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The pairing key still has the administrator role after pairing access control was enabled | <p>Pairing access control doesn't change the role of an existing pairing key. Existing pairing keys, which were previously hidden, become visible in the API Keys table once the feature is enabled.</p><p><br><br></p> | Edit the existing pairing key directly: go to **Settings > Configuration > API Keys**, locate the key, and change its role to **Pairing Key** or another role of your choice. |
| A new pairing attempt failed, and I don't see a pairing key at all                        | If an error occurs after the pairing key is generated (for example, a scope-seeding failure or an expired pairing request), Cortex automatically removes the orphaned key.                                              | Retry the pairing request. If the issue persists, contact Palo Alto Networks Customer Support.                                                                                |


---

# 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-xsiam/configure-cortex-xsiam/multi-tenant/child-tenant-management/pairing-accesss-control/manage-the-pairing-api-key.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.
