> 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/ibm-cloud-security-model-and-authentication.md).

# IBM Cloud security model and authentication

Understand how Cortex XDR authenticates to IBM Cloud with a read-only service ID API key, and how Cortex XDR protects the key.

Cortex XDR follows a security-first approach for IBM Cloud onboarding. Every permission granted to Cortex XDR is read-only and has a clear purpose. This topic describes how Cortex XDR authenticates to your IBM Cloud account, and how it protects the credential you provide.

## Why IBM Cloud uses an API key

For the other cloud service providers, Cortex XDR uses keyless trust, such as OIDC-based workload identity federation, so no long-lived credentials are stored. IBM Cloud doesn't support this type of trust for external identity providers. Instead, Cortex XDR authenticates with an API key that belongs to a read-only service ID in your account.

The Terraform authentication template creates the service ID and the API key. You then enter the API key in Cortex XDR when you manually connect the cloud instance. IBM Cloud is the only cloud service provider for which Cortex XDR stores a customer credential.

## Security principles

Cortex XDR applies the following principles to IBM Cloud onboarding:

* **Read-only access:** The service ID has only Viewer and Reader roles and read-only custom roles. It can't create, change, or delete any resource in your account.
* **Least privilege:** Custom roles contain only the specific read actions that Cortex XDR needs, for the services where no built-in role grants only read access.
* **Permission transparency:** The Terraform authentication template contains the complete set of roles and access policies. You can review the template before you run it.
* **Customer control:** You own the service ID and the API key. You can disable or delete them in the IBM Cloud console at any time to revoke Cortex XDR access immediately.

## How Cortex XDR protects the API key

Cortex XDR protects the API key in the following ways:

* **Encryption at rest:** Cortex XDR encrypts the API key with a dedicated encryption key for your tenant in Google Cloud Key Management Service (Cloud KMS). Cortex XDR never stores the API key in plain text.
* **Separation of duties:** The Cortex XDR service that receives and encrypts the API key can't decrypt it. Only the service that reads your account configuration can decrypt it.
* **Short-lived tokens:** Cortex XDR doesn't send the API key with every request. It exchanges the API key for a short-lived IBM Cloud IAM access token, and uses the token to read your account configuration.
* **Masked display:** After you connect the cloud instance, Cortex XDR displays only the last four characters of the API key.
* **Transport security:** The API key travels from your browser to Cortex XDR over an encrypted connection only.

## Authentication flow

Cortex XDR uses a single identity for all operations. The authentication flow works as follows:

1. Cortex XDR decrypts the stored API key when it needs to access your account.
2. Cortex XDR exchanges the API key for a short-lived IAM access token with the IBM Cloud IAM token service.
3. Cortex XDR uses the access token to read your account configuration as the service ID.
4. When the token expires, Cortex XDR requests a new one.

All requests run as the service ID, so you can audit Cortex XDR activity in IBM Cloud Activity Tracker by filtering on the service ID.

## Credentials you manage

Two different IBM Cloud API keys are involved in onboarding. Keep them separate.

| API key                                   | Who creates it                        | What it's used for                                                | Stored by Cortex XDR |
| ----------------------------------------- | ------------------------------------- | ----------------------------------------------------------------- | -------------------- |
| Your administrator API key (`IC_API_KEY`) | You, before onboarding                | Authenticates Terraform when you run the authentication template. | No                   |
| Service ID API key                        | The Terraform authentication template | Authenticates Cortex XDR as the read-only service ID.             | Yes, encrypted       |

## API key lifecycle

The service ID API key doesn't expire on a schedule. Rotate it when your security policy requires it, or when you suspect the key is compromised. Rotation creates a new key while the current key is still valid, so Cortex XDR keeps reading your account without interruption. For details, see [Rotate the IBM Cloud API key](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).

{% hint style="warning" %}
**Important:** Terraform writes the API key value to the Terraform state file (`terraform.tfstate`). Store the state file securely and restrict access to it.
{% endhint %}


---

# 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/ibm-cloud-security-model-and-authentication.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.
