> 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/xsiam-api/cloud-onboarding/cloud-onboarding-overview.md).

# Cloud Onboarding API overview

Public APIs for onboarding cloud service providers (CSPs) to Cortex XSIAM and managing the resulting cloud instances.

**Required license:** In Cortex XSIAM Premium, Cortex XSIAM Enterprise, or Cortex XSIAM NG SIEM, requires the Cortex Cloud Posture Management add-on. In Cortex XSIAM Enterprise Plus, requires the Data Collection add-on.

***

## What you can do with this API

* **Cloud instance management** — Create a cloud instance in pending state and download the authentication template to deploy in your CSP. Get details on existing cloud instances, and enable, disable, delete, or edit them.
* **Cloud account management** — Manage accounts within a cloud instance. A single cloud instance can contain multiple cloud accounts. Get, enable, or disable accounts within an instance.
* **Outpost management** — Create or edit templates for onboarding outpost scan environments.
* **General** — Utility endpoints for listing supported regions and retrieving outpost IDs.

***

## CSP reference

The table below summarizes every per-CSP constraint in one place. Detailed notes follow for fields that need more explanation.

|                                   | AWS                    | Azure                 | GCP                  | OCI                 | Alibaba Cloud        |
| --------------------------------- | ---------------------- | --------------------- | -------------------- | ------------------- | -------------------- |
| **`cloud_provider` value**        | `AWS`                  | `AZURE`               | `GCP`                | `OCI`               | `ALIBABA_CLOUD`      |
| **Partitions**                    | `COMMERCIAL`, `GOV`¹   | `COMMERCIAL`, `GOV`¹  | `COMMERCIAL` only    | `COMMERCIAL` only   | `COMMERCIAL` only    |
| **Scopes**                        | All three              | All three             | All three            | `ORGANIZATION` only | `ACCOUNT` only       |
| **Scan modes**                    | `MANAGED`, `OUTPOST`   | `MANAGED`, `OUTPOST`  | `MANAGED`, `OUTPOST` | `MANAGED` only      | `MANAGED` only       |
| **`account_details`**             | Not used               | Required²             | Not used             | Not used            | Not used             |
| **`collection_configuration`**    | Required               | Required              | Required             | Required            | Must not be provided |
| **Audit log `collection_method`** | `AUTOMATED`, `CUSTOM`  | `AUTOMATED`, `CUSTOM` | Not required         | `CUSTOM` only³      | N/A                  |
| **Account-level scope filter**    | `accounts`             | `subscriptions`       | `projects`           | `compartments`      | `accounts`           |
| **Org-level scope filter**        | `organizational_units` | `management_groups`   | `folders`            | Not supported       | Not supported        |

> ¹ `GOV` requires a FedRAMP-certified Cortex tenant.\
> ² `account_details.organization_id` must be the Azure tenant ID (UUID format).\
> ³ OCI requires `collection_method: CUSTOM` and a `custom_collectors` list (region, bucket name, compartment OCID per entry).

***

## Onboarding concepts

### Cloud partitions

Select the partition that matches your environment. Only AWS and Azure support the `GOV` partition; all other CSPs use `COMMERCIAL` only.

### Scope

The scope defines which accounts Cortex XSIAM monitors. Use your CSP's organizational hierarchy to onboard accounts individually or collectively.

| Scope               | AWS                 | Azure            | GCP          | OCI     | Alibaba Cloud |
| ------------------- | ------------------- | ---------------- | ------------ | ------- | ------------- |
| Entire organization | Organization        | Tenant           | Organization | Tenancy | —             |
| Group of accounts   | Organizational Unit | Management Group | Folder       | —       | —             |
| Single account      | Account             | Subscription     | Project      | —       | Account       |

**OCI:** Only tenancy-level (organization) onboarding is supported.\
**Alibaba Cloud:** Only single-account onboarding is supported. Create a separate cloud instance for each account.

> You cannot expand the scope of a cloud instance after deployment. Start with the broadest anticipated scope and use account or region exclusions to narrow it.

### Scan mode

* **`MANAGED`** (recommended) — Scanning runs within the Cortex XSIAM environment. No additional setup required.
* **`OUTPOST`** — Scanning runs on infrastructure you deploy in a dedicated CSP account. Requires additional permissions and may incur additional cloud costs. Set `scan_env_id` to the outpost ID (retrieved from `GET /public_api/v1/cloud_onboarding/get_outposts`).

OCI and Alibaba Cloud support `MANAGED` only.

### Scope filters

Use `scope_modifications` to limit which regions or accounts Cortex XSIAM monitors within the deployed scope. Each filter object has the same shape:

```json
{
  "enabled": true,
  "type": "INCLUDE" | "EXCLUDE",
  "<filter_field>": ["<id1>", "<id2>"]
}
```

Set `enabled: false` (or omit the object) to apply no filter. When `enabled: true`, `type` and the ID list are required.

**Account and OU filters** narrow which accounts are scanned within the deployed scope. The field name varies by CSP:

| Filter        | AWS                    | Azure               | GCP        | OCI            | Alibaba Cloud |
| ------------- | ---------------------- | ------------------- | ---------- | -------------- | ------------- |
| Account-level | `accounts`             | `subscriptions`     | `projects` | `compartments` | `accounts`    |
| Org-level     | `organizational_units` | `management_groups` | `folders`  | Not supported  | Not supported |

**Region filters** (`regions`) are supported for all CSPs and use the same `enabled` / `type` / `regions` shape.

**OU filters are recursive.** Selecting or excluding an OU node applies to all accounts beneath it in the hierarchy. For example, excluding one OU that contains 170 accounts excludes all 170 with a single ID.

#### Combining OU and account filters

You can enable both an OU filter and an account filter at the same time, but both must use the same mode — either both `INCLUDE` or both `EXCLUDE`. Mixing modes is not supported and returns a validation error at onboarding.

When both filters are active:

* **Both set to INCLUDE** — the result is a union. Cortex XSIAM monitors all accounts that fall under the included OUs, plus any individually included accounts.
* **Both set to EXCLUDE** — the result is an intersection of exclusions. Cortex XSIAM excludes any account that is either under an excluded OU or in the excluded accounts list.

Excluded accounts are not scanned and are removed from the asset inventory after the next account discovery cycle runs. Until then, they remain temporarily visible on the Cloud Instances page and in the asset inventory.

> Exclusions do not remove onboarding resources already deployed in your CSP, and do not stop data sources that operate at the parent scope (such as audit log collection) from continuing to collect data.

***

## Security capabilities

Security capabilities are configured in `additional_capabilities`. All fields default to `false`. Permissions, Discovery Engine, and Identity Security are always enabled and cannot be disabled.

| Capability                 | API field                          | AWS            | Azure          | GCP | OCI | Alibaba Cloud |
| -------------------------- | ---------------------------------- | -------------- | -------------- | --- | --- | ------------- |
| Permissions                | *(always on)*                      | Yes            | Yes            | Yes | Yes | Yes           |
| Discovery Engine           | *(always on)*                      | Yes            | Yes            | Yes | Yes | Yes           |
| Identity Security          | *(always on)*                      | Yes            | Yes            | Yes | Yes | No            |
| Audit Logs                 | `collection_configuration`⁴        | Yes            | Yes            | Yes | Yes | No            |
| Agentless Disk Scanning    | `agentless_disk_scanning`          | Yes            | Yes            | Yes | Yes | Feature-flag⁵ |
| Data Security Posture Mgmt | `data_security_posture_management` | Yes / No (GOV) | Yes / No (GOV) | Yes | Yes | No            |
| Registry Scanning          | `registry_scanning`⁶               | Yes            | Yes            | Yes | Yes | No            |
| Serverless Scanning        | `serverless_scanning`              | Yes            | Yes            | Yes | No  | No            |
| XSIAM Analytics            | `xsiam_analytics`                  | Yes            | Yes            | Yes | No  | No            |
| Kubernetes Security        | `kubernetes_security`              | Yes            | Yes            | Yes | No  | No            |
| Automation                 | `automation`⁷                      | Yes            | Yes            | Yes | No  | No            |

> ⁴ Audit Logs are configured via `collection_configuration.audit_logs.enabled`, not `additional_capabilities`. For AWS with `collection_method: AUTOMATED`, the `data_events` boolean is also required.\
> ⁵ Alibaba Cloud agentless disk scanning requires the `enable_ads_for_alibaba_cloud` feature flag on your tenant. All other capabilities must be `false` or omitted.\
> ⁶ When `registry_scanning: true`, `registry_scanning_options` is also required. When `false`, omit `registry_scanning_options`.\
> ⁷ When `automation: true`, `automation_log_level` is also required. Valid values: `OFF`, `Debug`, `Verbose`.

### GOV partition restrictions

When `cloud_partition` is `GOV` (AWS or Azure only):

* **DSPM is not available.** Setting `data_security_posture_management: true` returns a validation error.
* All other capabilities marked Yes for AWS or Azure in the table above remain available.

### OCI license restrictions

| License               | Allowed additional capabilities                                                    |
| --------------------- | ---------------------------------------------------------------------------------- |
| Standard              | `agentless_disk_scanning`, `registry_scanning`, `data_security_posture_management` |
| XSIAM Enterprise Plus | None — all must be `false`                                                         |

***

## Audit log collection

When enabled, audit logs power real-time threat detection, near-real-time asset discovery, and investigation context. Configure audit logs in `collection_configuration.audit_logs`.

| Field                   | Description                                                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled`               | Set to `true` to enable audit log collection.                                                                                        |
| `collection_method`     | `AUTOMATED` (Cortex sets up log infrastructure) or `CUSTOM` (use your existing setup).                                               |
| `data_events`           | AWS only, `AUTOMATED` method only. Set to `true` to include data-plane events.                                                       |
| `is_control_tower_byob` | AWS Organization scope only, `CUSTOM` method only. Set to `true` for Control Tower BYOB configurations.                              |
| `custom_collectors`     | OCI only. Required when `collection_method: CUSTOM`. Provide a list of objects with `region`, `bucket_name`, and `compartment_ocid`. |

***

## Custom resource tags

Use `custom_resources_tags` to apply key-value tags to all resources the authentication template creates in your CSP. The `managed_by: paloaltonetworks` tag is added by default and cannot be removed.

***

## Regions

The `scope_modifications.regions` field is required for all CSPs. To retrieve the valid region list for a given provider and partition, call:

```
POST /public_api/v1/cloud_onboarding/list_cloud_provider_regions
```

***

## Manual onboarding

Manual onboarding lets you provision the required CSP resources yourself — using your own tooling, pipelines, or governance processes — instead of deploying a Cortex-generated CloudFormation or Terraform template. This is useful when your organization requires full control over IAM role creation, audit-log infrastructure, or resource naming.

**Supported CSPs:** AWS, Azure, and GCP only. OCI and Alibaba Cloud do not support manual provisioning.

**Audit log collection method:** Manual onboarding always uses `collection_method: CUSTOM`. You must provide an existing S3 bucket (AWS), Event Hub (Azure), or equivalent log sink (GCP) — Cortex does not create log infrastructure in manual mode.

***

### Manual onboarding workflow

The manual onboarding flow uses four API calls in sequence. Steps 2 and 3 involve work in your CSP environment between the API calls.

```
1. get_manual_connector_identifiers  →  obtain identifiers file
2. [CSP] Create resources            →  use identifiers section as reference
3. [CSP] Collect output values       →  populate manual_details section
4. create_instance                   →  finalize onboarding in Cortex
```

#### Step 1 — Generate the identifiers file

Call `POST /public_api/v1/cloud_onboarding/get_manual_connector_identifiers` with the same `cloud_provider`, `scope`, `scan_mode`, and security capabilities you intend to use for the instance.

The response contains a JSON object with two sections:

| Section          | Contents                                                                                                                                                        |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `identifiers`    | Pre-populated Cortex-generated values (role names, external IDs, OIDC audience, collector service account IDs). Use these as input when creating CSP resources. |
| `manual_details` | Initially empty fields. You populate these with values retrieved from your CSP environment after creating the resources.                                        |

**Example request:**

```json
{
  "request_data": {
    "cloud_provider": "AWS",
    "scope": "ORGANIZATION",
    "scan_mode": "MANAGED",
    "collection_configuration": {
      "audit_logs": {
        "enabled": true,
        "collection_method": "CUSTOM"
      }
    },
    "additional_capabilities": {
      "agentless_disk_scanning": true
    }
  }
}
```

#### Step 2 — Create CSP resources

Using the values in the `identifiers` section as a reference, create the required resources in your CSP:

**AWS**

| Resource                                                                                       | How to use the identifier                                                           |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| Cortex Platform IAM role                                                                       | Use `CortexPlatformRoleName` as the role name; use `ExternalID` in the trust policy |
| CloudTrail S3 bucket                                                                           | Use `CloudTrailLogsBucket` to point to your existing bucket                         |
| CloudTrail SQS queue                                                                           | Create an SQS queue subscribed to S3 event notifications                            |
| CloudTrail read role (if audit logs enabled)                                                   | Use `Audience` and `CollectorServiceAccountId` in the OIDC trust policy             |
| Scanner role (if outpost scanning, DSPM, registry scanning, or serverless scanning is enabled) | Use `OutpostRoleArn` as the assume-role principal                                   |

**Azure**

| Resource                              | How to use the identifier                                                                                                    |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Cortex service principal              | Already present in your tenant after admin consent                                                                           |
| Custom roles                          | Create `Cortex-Platform-Base` and capability-specific roles (DSPM, ADS, Registry, Automation, KSPM) at the appropriate scope |
| User-Assigned Managed Identity (UAMI) | Required if audit logs are enabled; configure workload identity federation using `CollectorServiceAccountId`                 |
| Event Hub namespace and hub           | Required if audit logs are enabled                                                                                           |

**GCP**

| Resource                 | How to use the identifier                                                       |
| ------------------------ | ------------------------------------------------------------------------------- |
| Platform service account | Create and bind the Cortex platform service account with the required IAM roles |
| Scanner service account  | Required if agentless disk scanning or registry scanning is enabled             |
| Audit log sink           | Required if audit logs are enabled                                              |

#### Step 3 — Populate the `manual_details` section

After creating the CSP resources, retrieve the output values and populate the `manual_details` section of the identifiers file:

**AWS example values to collect:**

| Field                 | How to retrieve                                                                         |
| --------------------- | --------------------------------------------------------------------------------------- |
| `account_id`          | `aws sts get-caller-identity --query Account --output text`                             |
| `role_arn`            | `aws iam get-role --role-name "${CORTEX_ROLE_NAME}" --query Role.Arn --output text`     |
| `external_id`         | From the `identifiers.ExternalID` field                                                 |
| `sqs_queue_url`       | `aws sqs get-queue-url --queue-name "${SQS_QUEUE_NAME}" --query QueueUrl --output text` |
| `cloudtrail_role_arn` | `aws iam get-role --role-name "${LOGS_ROLE_NAME}" --query Role.Arn --output text`       |

**Azure example values to collect:**

| Field                         | How to retrieve                                         |
| ----------------------------- | ------------------------------------------------------- |
| `tenant_id`                   | Azure portal → Microsoft Entra ID → Overview            |
| `subscription_id`             | Azure portal → Subscriptions                            |
| `eventhub_audit_client_id`    | Client ID of the UAMI created in Phase 4                |
| `namespace` / `eventhub_name` | From the Event Hub namespace and hub created in Phase 4 |

#### Step 4 — Create the instance

Call `POST /public_api/v1/cloud_onboarding/create_instance` with the same configuration used in Step 1, plus the completed `manual_details` object:

```json
{
  "request_data": {
    "cloud_provider": "AWS",
    "scope": "ORGANIZATION",
    "scan_mode": "MANAGED",
    "manual_details": {
      "account_id": "123456789012",
      "role_arn": "arn:aws:iam::123456789012:role/CortexPlatformRole-m-a-9992206592268",
      "external_id": "1d890e40-2f50-4e55-b9db-bcce534213a8",
      "sqs_queue_url": "https://sqs.us-east-1.amazonaws.com/123456789012/cortex-cloudtrail-queue",
      "cloudtrail_role_arn": "arn:aws:iam::123456789012:role/CortexCloudTrailRole"
    },
    "collection_configuration": {
      "audit_logs": {
        "enabled": true,
        "collection_method": "CUSTOM"
      }
    },
    "additional_capabilities": {
      "agentless_disk_scanning": true
    }
  }
}
```

A successful response returns the new instance ID. The instance is now active in Cortex XSIAM.

***

### Editing a manually-onboarded instance

To update the configuration of an existing manually-onboarded instance:

1. **Inspect current state** — Call `POST /public_api/v1/cloud_onboarding/get_edit_instance_details` to retrieve the current configuration and any pending changes.
2. **Check available capabilities** — Optionally call `POST /public_api/v1/cloud_onboarding/resolve_connector_security_capabilities` to confirm which capabilities are valid for your CSP/scope/partition.
3. **Submit the edit** — Call `POST /public_api/v1/cloud_onboarding/edit_manual_instance` with the connector ID, updated configuration, and refreshed `manual_details`.
4. **Update CSP resources** — Re-create or update any CSP resources affected by the configuration change (for example, add a new IAM role if you enabled a new security capability).
5. **Mark as resolved** — Call `POST /public_api/v1/cloud_onboarding/manual_update_and_resolve` with the connector ID to clear the pending-update state in Cortex.

> **Immutable fields:** `scope`, `scan_mode`, and the root account identifier (for example, `account_id` for AWS) cannot be changed after onboarding. Delete the instance and create a new one to change these.

***

## Pending cloud instances

A pending cloud instance is created when you call the onboard endpoint but before the generated authentication template is deployed in your CSP. A single pending instance can produce multiple cloud instances that share the same configuration. Pending instances are automatically removed after 30 days.

You can exclude pending cloud instances from the `/public_api/v1/cloud_onboarding/get_instances` response by using the following filter in conjuction with any other filters you want to apply:

```json
"filter":{
  "AND":[
  { 
    "SEARCH_FIELD": "STATUS",
    "SEARCH_TYPE": "NEQ",
    "SEARCH_VALUE": "PENDING"
   }
  ]
}
```

***

### Deleting a manually-onboarded pending cloud instance

When you call the onboarding or edit endpoints, Cortex generates a pending cloud instance. If you need to remove a specific pending cloud instance (for example, because it was generated with incorrect settings), call `POST /public_api/v1/cloud_onboarding/delete_instance_template` with the instance ID.

Deleting a pending cloud instance does not delete the cloud instance itself, nor does it remove any resources already deployed in your CSP. To remove the cloud instance, use `POST /public_api/v1/cloud_onboarding/delete_instance`.

GOV regions are separate from commercial regions:

* **AWS GOV:** `us-gov-east-1`, `us-gov-west-1`
* **Azure GOV:** `usgovarizona`, `usgovtexas`, `usgovvirginia`, `global`


---

# 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/xsiam-api/cloud-onboarding/cloud-onboarding-overview.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.