> 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/configure-cortex-xdr/cortex-xdr-data-sources/cloud-service-provider-csp-onboarding/ibm-cloud-cloud-onboarding/rotate-the-ibm-cloud-api-key.md).

# Rotate the IBM Cloud API key

Rotate the IBM Cloud service ID API key that Cortex XDR uses, without interrupting the monitoring of your IBM Cloud account.

Cortex XDR authenticates to your IBM Cloud account with a service ID API key that doesn't expire. Rotate the key when your security policy requires it, or when you suspect the key is compromised. You also use this procedure to recover if the key that Cortex XDR uses is deleted in IBM Cloud.

## How rotation works

The Terraform authentication template manages two API key slots for the service ID: `cortex-<suffix>-api-key` and `cortex-<suffix>-api-key-2`. Each rotation creates a new key in the slot that Cortex XDR isn't using, and leaves the current key in place. Cortex XDR keeps reading your account with the current key until you provide the new one, so monitoring continues without interruption.

The first rotation creates the second key. Later rotations alternate between the two slots, and replace the older key each time.

## Before you begin

Ensure that you have the following:

* The directory where you originally ran the Terraform template, including the Terraform state file (`terraform.tfstate`).
* An IBM Cloud administrator API key that meets the [prerequisites for onboarding IBM Cloud](https://cortex-docs.paloaltonetworks.com/cortex-xdr/configure-cortex-xdr/cortex-xdr-data-sources/cloud-service-provider-csp-onboarding/ibm-cloud-cloud-onboarding/prerequisites-for-onboarding-ibm-cloud.md).

## Request a new API key in Cortex XDR

Start the rotation by editing the cloud instance. Cortex XDR generates an updated Terraform template that creates the new key. For other edits, such as changing the tags or the regions in scope, see [Edit an IBM Cloud cloud instance](https://cortex-docs.paloaltonetworks.com/cortex-xdr/configure-cortex-xdr/cortex-xdr-data-sources/cloud-service-provider-csp-onboarding/ibm-cloud-cloud-onboarding/edit-an-ibm-cloud-cloud-instance.md).

1. In Cortex XDR, select **Settings → Data Sources & Integrations**, and then open the **IBM Cloud** cloud instances.
2. Right-click the cloud instance and select **Configuration**.
3. Turn on the **API Key** toggle.

   The **Account ID** field is read-only. You can't change the IBM Cloud account of an existing cloud instance.
4. Click **Save**. Cortex XDR generates an updated Terraform template, and the cloud instance shows pending changes.
5. Click **Download Terraform** to download the updated template.

{% hint style="info" %}
**Note:** If you save the edit again before you apply it, Cortex XDR reuses the same pending rotation. It doesn't skip a key slot.
{% endhint %}

## Apply the updated template

Run the updated template in the same directory as the original deployment, so Terraform uses the existing state file.

1. Navigate to the original Terraform directory and extract the updated template files there. Overwrite the existing template files, but keep the Terraform state file.

   ```bash
   cd ~/terraform/ibm-cloud-connector-1
   tar -xzvf <your_updated_template>.tar.gz
   ```
2. Set your IBM Cloud administrator API key as an environment variable:

   ```bash
   export IC_API_KEY="<your IBM Cloud administrator API key>"
   ```
3. Apply the updated configuration:

   ```bash
   terraform init
   terraform apply --var-file=template_params.tfvars
   ```
4. Review the plan before you approve it. Check the following:

   * The plan adds or replaces only one API key (`ibm_iam_service_api_key`) and changes one key marker (`terraform_data`). The first rotation shows `Plan: 1 to add, 1 to change, 0 to destroy.` Later rotations show `Plan: 1 to add, 1 to change, 1 to destroy.` If you also changed tags in the same edit, the plan also changes the tags resource.
   * The service ID, custom roles, and access policies don't appear in the plan.

   If the plan shows other changes, don't approve it. You might be running the template in a directory without the original Terraform state file. Return to the original directory, or contact Palo Alto Networks support.

   When the plan is correct, enter `yes` to approve it. Terraform creates the new API key and doesn't change the key that Cortex XDR currently uses.
5. Retrieve the new values:

   ```bash
   terraform output account_id
   terraform output service_id
   terraform output template_id
   terraform output api_key
   ```

{% hint style="warning" %}
**Important:** Terraform shows the `api_key` value in clear text in the output of `terraform apply`, `terraform plan`, and `terraform output`. Copy the key securely. Don't share, log, or paste Terraform output, for example in support cases or chat, without removing the key.
{% endhint %}

## Apply the new API key in Cortex XDR

Provide the new API key to Cortex XDR to complete the rotation.

1. On the **Cloud Instances** page, right-click the cloud instance and select **Manually apply edit**.
2. In the **API Key** field, replace the masked value with the value of the `api_key` output. The **IBM Cloud Account ID** and **Service ID** fields are read-only.
3. Click **Connect**.

Cortex XDR encrypts and stores the new API key, and starts using it. The cloud instance exits the pending changes state.

{% hint style="warning" %}
**Important:** If you leave the **API Key** field empty or unchanged, Cortex XDR rejects the edit. This protects you from keeping a key that the next rotation replaces.
{% endhint %}

## Remove the previous API key (optional)

After a rotation, your IBM Cloud account has two API keys for the service ID: the key that Cortex XDR now uses, and the previous key. Keeping both keys is safe. The next rotation replaces the previous key automatically.

If your security policy requires a single API key, delete the previous key in the IBM Cloud console. Do this only after you complete **Manually apply edit**. Identify the key by its name, not by its creation date:

1. In the original Terraform directory, open `template_params.tfvars` and find the `key_rotation` value.
2. Delete the key that Cortex XDR doesn't use:
   * If `key_rotation` is an even number, Cortex XDR uses `cortex-<suffix>-api-key`. Delete `cortex-<suffix>-api-key-2`.
   * If `key_rotation` is an odd number, Cortex XDR uses `cortex-<suffix>-api-key-2`. Delete `cortex-<suffix>-api-key`.

Terraform recreates the deleted key the next time you run the template.

## Recover from a deleted API key

If someone deletes the API key that Cortex XDR uses in the IBM Cloud console, Cortex XDR can't authenticate, and the cloud instance shows a permissions error. To recover, follow the full rotation procedure. Terraform recreates the missing key and outputs a new working key.

## Cancel a pending rotation

If you saved the rotation but you don't want to apply it, revoke the pending changes. On the **Cloud Instances** page, click the **Configuration** pencil icon for the cloud instance, and under **Manage unsaved changes**, select **Revoke pending changes**. For more information, see [Edit your onboarded CSP configuration](https://cortex-docs.paloaltonetworks.com/cortex-xdr/configure-cortex-xdr/cortex-xdr-data-sources/cloud-service-provider-csp-onboarding/edit-your-onboarded-csp-configuration.md).

If you already ran the updated template, the new key exists in IBM Cloud but Cortex XDR doesn't use it. The next rotation reuses that key slot.


---

# 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/configure-cortex-xdr/cortex-xdr-data-sources/cloud-service-provider-csp-onboarding/ibm-cloud-cloud-onboarding/rotate-the-ibm-cloud-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.
