Scopes

Operations for managing Scope-Based Access Control (SBAC) configurations for users, groups, and API keys.

Retrieve an existing scope

get

This API endpoint allows retrieving the scope details for a specific entity type and entity ID. For possible 'mode' and 'entity_type' values, please refer to the enum documentation for 'ModeType' and 'EntityType'.

Path parameters

entity_typestring · enumRequired

The type of entity - Possible values: user (Signifies that the entity is a user), usergroup (Signifies that the entity is a custom or AD user group), apikey (Signifies that the entity is an API key)

Possible values:

entity_idstringRequired

Full id of the entity

Responses

200

Successfully retrieved scope

application/json

dataobjectRequired

401

Unauthorized access

application/json

403

Unauthorized access due to lack of sufficient permissions. This includes Instance Administrator privilege escalation errors: non-admin API keys cannot assign, modify, or delete entities that have the Instance Administrator role.

application/json

500

Internal server error. A unified status for API communication type errors.

get/platform/iam/v1/scope/{entity_type}/{entity_id}

GET /platform/iam/v1/scope/{entity_type}/{entity_id} HTTP/1.1
Host: api-cortex.paloaltonetworks.com
Accept: */*

{
  "data": {
    "assets": {
      "mode": "scope",
      "asset_groups": [
        {
          "asset_group_id": 1,
          "asset_group_name": "Asset Test Group 1"
        },
        {
          "asset_group_id": 2,
          "asset_group_name": "Asset Test Group 2"
        },
        {
          "asset_group_id": 3,
          "asset_group_name": "Asset Test Group 3"
        }
      ]
    },
    "datasets_rows": {
      "default_filter_mode": "no_scope",
      "filters": [
        {
          "dataset": "dataset_1",
          "filter": "_collector_name = filter_collector_1"
        },
        {
          "dataset": "dataset_2",
          "filter": "_collector_name = filter_collector_2"
        }
      ]
    },
    "endpoints": {
      "endpoint_groups": {
        "mode": "scope",
        "tags": [
          {
            "tag_id": "EG:1",
            "tag_name": "test-eg-1"
          }
        ]
      },
      "endpoint_tags": {
        "mode": "any",
        "tags": [
          {
            "tag_id": null,
            "tag_name": "Any"
          }
        ]
      }
    },
    "cases_issues": {
      "mode": "scope",
      "tags": [
        {
          "tag_id": "DOM:4",
          "tag_name": "Health"
        },
        {
          "tag_id": "DOM:3",
          "tag_name": "IT"
        }
      ]
    }
  }
}

Edit an existing scope

put

This API endpoint allows editing the scope details for a specific entity type and entity ID. For possible 'mode' and 'entity_type' values, please refer to the enum documentation for 'ModeType' and 'EntityType'. Please note that the 'datasets_rows' field can only be passed in to the request body if the dataset scope configuration is enabled for the tenant. Dataset row-level scoping is available only on XSIAM tenants where the feature has been activated — it is not configurable through the UI or a public API. Contact your Palo Alto Networks account team to enable this feature. When dataset scope is enabled, the 'datasets_rows' field becomes mandatory in every scope edit request; omitting it returns a 400 error.

Path parameters

entity_typestring · enumRequired

The type of entity - Possible values: user (Signifies that the entity is a user), usergroup (Signifies that the entity is a custom or AD user group), apikey (Signifies that the entity is an API key)

Possible values:

entity_idstringRequired

Full id of the entity

Body

Responses

200

Scope edited successfully

application/json

400

Bad request for scope edit call

application/json

401

Unauthorized access

application/json

403

Unauthorized access due to lack of sufficient permissions. This includes Instance Administrator privilege escalation errors: non-admin API keys cannot assign, modify, or delete entities that have the Instance Administrator role.

application/json

500

Internal server error. A unified status for API communication type errors.

put/platform/iam/v1/scope/{entity_type}/{entity_id}

PUT /platform/iam/v1/scope/{entity_type}/{entity_id} HTTP/1.1
Host: api-cortex.paloaltonetworks.com
Content-Type: application/json
Accept: */*
Content-Length: 489

{
  "request_data": {
    "endpoints": {
      "endpoint_groups": {
        "names": [
          "test-eg-1"
        ],
        "mode": "scope"
      },
      "endpoint_tags": {
        "names": [],
        "mode": "any"
      }
    },
    "cases_issues": {
      "mode": "scope",
      "include_cases_issues_empty_entities": true,
      "names": [
        "Health",
        "IT"
      ]
    },
    "assets": {
      "mode": "scope",
      "asset_group_ids": [
        1,
        2,
        3
      ]
    },
    "datasets_rows": {
      "filters": [
        {
          "dataset": "test-dataset-1",
          "filter": "_collector_name = bu2_collector"
        },
        {
          "dataset": "test-dataset-2",
          "filter": "_collector_name = bu2_collector"
        }
      ],
      "default_filter_mode": "no_scope"
    }
  }
}

{
  "data": {
    "message": "Scope updated for user [e-mail] successfully"
  }
}