Edit an existing scope

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

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 config is enabled.

Path parameters

entity_type EntityType required

Full name of the entity's type

entity_id String required

Full id of the entity

Example: entityId_example

CLIENT REQUEST

          curl -X 'PUT'

        -H
        'Accept: application/json'
      

        -H
        'Content-Type: application/json'
      

      'https://api-cortex.paloaltonetworks.com/platform/iam/v1/scope/{entity_type}/{entity_id}'
    

      -d
      '{
  "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"
    }
  }
}'
    


      

import http.client

conn = http.client.HTTPSConnection("api-")

payload = "{\"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\"}}}"

headers = { 'content-type': "application/json" }

conn.request("PUT", "%7Bfqdn%7D/platform/iam/v1/scope/%7Bentity_type%7D/%7Bentity_id%7D", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

require 'uri'
require 'net/http'
require 'openssl'

url = URI("https://api-/%7Bfqdn%7D/platform/iam/v1/scope/%7Bentity_type%7D/%7Bentity_id%7D")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE

request = Net::HTTP::Put.new(url)
request["content-type"] = 'application/json'
request.body = "{\"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\"}}}"

response = http.request(request)
puts response.read_body

const data = JSON.stringify({
  "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"
    }
  }
});

const xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("PUT", "https://api-/%7Bfqdn%7D/platform/iam/v1/scope/%7Bentity_type%7D/%7Bentity_id%7D");
xhr.setRequestHeader("content-type", "application/json");

xhr.send(data);

HttpResponse<String> response = Unirest.put("https://api-/%7Bfqdn%7D/platform/iam/v1/scope/%7Bentity_type%7D/%7Bentity_id%7D")
  .header("content-type", "application/json")
  .body("{\"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\"}}}")
  .asString();

import Foundation

let headers = ["content-type": "application/json"]
let parameters = ["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"
    ]
  ]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api-/%7Bfqdn%7D/platform/iam/v1/scope/%7Bentity_type%7D/%7Bentity_id%7D")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-/%7Bfqdn%7D/platform/iam/v1/scope/%7Bentity_type%7D/%7Bentity_id%7D",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PUT",
  CURLOPT_POSTFIELDS => "{\"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\"}}}",
  CURLOPT_HTTPHEADER => [
    "content-type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

CURL *hnd = curl_easy_init();

curl_easy_setopt(hnd, CURLOPT_CUSTOMREQUEST, "PUT");
curl_easy_setopt(hnd, CURLOPT_URL, "https://api-/%7Bfqdn%7D/platform/iam/v1/scope/%7Bentity_type%7D/%7Bentity_id%7D");

struct curl_slist *headers = NULL;
headers = curl_slist_append(headers, "content-type: application/json");
curl_easy_setopt(hnd, CURLOPT_HTTPHEADER, headers);

curl_easy_setopt(hnd, CURLOPT_POSTFIELDS, "{\"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\"}}}");

CURLcode ret = curl_easy_perform(hnd);

var client = new RestClient("https://api-/%7Bfqdn%7D/platform/iam/v1/scope/%7Bentity_type%7D/%7Bentity_id%7D");
var request = new RestRequest(Method.PUT);
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\"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\"}}}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Body parameters

required

application/json

request_dataobjectrequired

Scope configuration data to update

assetsobject

Asset scope configuration for request payloads

modestring (Enum)

Access mode for assets. Use 'scope' to limit access to specific asset groups, 'see_all' for full access, or 'no_scope' for no access

Allowed values:"no_scope""see_all""scope"

asset_group_idsarray[integer]

List of asset group IDs when configuring scope (used in PUT requests)

datasets_rowsobject

Dataset rows scope configuration for filtering data access

default_filter_modestring (Enum)

Default behavior for datasets not explicitly listed in filters. 'no_scope' means no access to unlisted datasets, 'see_all' means full access to unlisted datasets

Allowed values:"no_scope""see_all"

filtersarray

List of dataset-specific filters to apply row-level access control

[

datasetstringrequired

Name of the dataset to apply the filter to

filterstringrequired

Filter expression to limit data access (e.g., '_collector_name = collector_1')

]

endpointsobject

Endpoint scope configuration for request payloads

endpoint_groupsobject

Endpoint groups scope configuration for requests

modestring (Enum)

Access mode for endpoint groups

Allowed values:"no_scope""see_all""scope""any"

namesarray[string]

List of endpoint group names when configuring scope

endpoint_tagsobject

Endpoint tags scope configuration for requests

modestring (Enum)

Access mode for endpoint tags

Allowed values:"no_scope""see_all""scope""any"

namesarray[string]

List of endpoint tag names when configuring scope

cases_issuesobject

Cases and issues scope configuration for requests

modestring (Enum)

Access mode for cases and issues

Allowed values:"no_scope""see_all""scope"

include_cases_issues_empty_entitiesboolean

Whether to include cases and issues that have no associated entities/tags

namesarray[string]

List of tag names when configuring scope

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

Responses

Scope edited successfully

Body

application/json

dataobject

messagestringrequired

Success message indicating the scope was edited

RESPONSE
{
  "data": {
    "message": "Scope updated for user user@email.com successfully"
  }
}

Bad request for scope edit call

Body

application/json

dataobject

err_msgstringrequired

Error message describing the issue

metadataobject

err_extrastringrequired

Additional error details

err_codeintegerrequired

HTTP error code

RESPONSE
{
  "data": {
    "err_msg": "The request contains invalid or missing parameters.",
    "metadata": {
      "err_extra": "The scope name test_scope_01 does not exist.",
      "err_code": 400
    }
  }
}

Unauthorized access

Body

application/json

RESPONSE
{
  "reply": {
    "err_code": 401,
    "err_msg": "Public API request unauthorized",
    "err_extra": null
  }
}

Unauthorized access due to lack of sufficient permissions

Body

application/json

replyobject

err_msgstringrequired

err_extrastring

err_codeinteger

metadataobjectrequired

RESPONSE
{
  "reply": {
    "err_code": 403,
    "err_msg": "Forbidden. Access was denied to this resource.",
    "err_extra": "Insufficient permissions for api key",
    "metadata": {}
  }
}

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