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

# Cloud Onboarding API overview

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

**Required license:** Cortex Cloud Posture Management or Cortex Cloud Runtime Security.

***

## 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 Cloud 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 Cloud 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 Cloud 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 Cloud 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 Cloud excludes any account that is either under an excluded OU or in the excluded accounts list.

Excluded accounts are not scanned and do not appear in the asset inventory, but remain visible on the Cloud Instances page.

> 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 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
```

GOV regions are separate from commercial regions:

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

***

## 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"
   }
  ]
}
```


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cortex-docs.paloaltonetworks.com/cortex-cloud-api/cloud-onboarding/cloud-onboarding-overview.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.