Cortex XDR 5.x

Cloud Onboarding API overview

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

Required license: Cortex Cloud Posture Management.

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 only

Scopes

All three

ORGANIZATION only

ACCOUNT only

Scan modes

MANAGED, OUTPOST

MANAGED only

account_details

Not used

Required²

Not used

collection_configuration

Required

Must not be provided

Audit log collection_method

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

¹ 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 XDR 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 XDR 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 XDR monitors within the deployed scope. Each filter object has the same shape:

{
  "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

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

Discovery Engine

(always on)

Yes

Identity Security

(always on)

Yes

Audit Logs

collection_configuration⁴

Yes

Agentless Disk Scanning

agentless_disk_scanning

Yes

Feature-flag⁵

Data Security Posture Mgmt

data_security_posture_management

Yes / No (GOV)

Yes

Registry Scanning

registry_scanning⁶

Yes

Serverless Scanning

serverless_scanning

Yes

XSIAM Analytics

xsiam_analytics

Yes

Kubernetes Security

kubernetes_security

Yes

Automation

automation⁷

Yes

⁴ 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:

{
  "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:

{
  "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 XDR.

Editing a manually-onboarded instance

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

Inspect current state — Call POST /public_api/v1/cloud_onboarding/get_edit_instance_details to retrieve the current configuration and any pending changes.
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.
Submit the edit — Call POST /public_api/v1/cloud_onboarding/edit_manual_instance with the connector ID, updated configuration, and refreshed manual_details.
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).
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:

"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

PreviousModels

NextCloud Instance Management

Last updated 5 hours ago

Was this helpful?

What you can do with this API

CSP reference

Onboarding concepts

Cloud partitions

Scope

Scan mode

Scope filters

Combining OU and account filters

Security capabilities

GOV partition restrictions

OCI license restrictions

Audit log collection

Custom resource tags

Regions

Manual onboarding

Manual onboarding workflow

Step 1 — Generate the identifiers file

Step 2 — Create CSP resources

Step 3 — Populate the manual_details section

Step 4 — Create the instance

Editing a manually-onboarded instance

Pending cloud instances

Deleting a manually-onboarded pending cloud instance

Step 3 — Populate the `manual_details` section