docs(iot): IPR-2072 organization hierarchy API by TomorrowMC · Pull Request #1580 · PaloAltoNetworks/pan.dev

TomorrowMC · 2026-11-09T20:20:13Z

Documents the six new Device Security public endpoints for managing the organization (site group) hierarchy by name (IPR-2072):

GET /iot/pub/v1/organization the hierarchy as one list of { name, type, parent, path }; group and type filters
POST /iot/pub/v1/organization create 1-1000 groups; a parent may be a group listed earlier in the same request
PUT /iot/pub/v1/organization rename and/or move one group
DELETE /iot/pub/v1/organization delete one group; its subgroups and sites move to its parent
POST /iot/pub/v1/organization/sites assign sites to a group
DELETE /iot/pub/v1/organization/sites unassign sites from a group

Also states on GET/POST/PUT /site that a null group means the site sits directly under the top-level group.

Not to be merged until the endpoints are released.

Document the six Device Security public endpoints that read and manage the organization (site group) hierarchy by name: - GET /iot/pub/v1/organization: the hierarchy as one list of { name, type, parent, path }, with `group` and `type` filters - POST /iot/pub/v1/organization: create 1-1000 groups; a parent may be a group listed earlier in the same request - PUT /iot/pub/v1/organization: rename and/or move one group - DELETE /iot/pub/v1/organization: delete one group; its subgroups and sites move to its parent - POST /iot/pub/v1/organization/sites: assign sites to a group - DELETE /iot/pub/v1/organization/sites: unassign sites from a group On GET, POST and PUT /site, state that a `null` group means the site sits directly under the top-level group.

joey-nolan-panw

LGTM

TomorrowMC · 2026-11-10T21:44:21Z

@cnguyen1-panw Can you please help review this, thanks!

github-actions · 2026-11-10T23:00:54Z

Visit the preview URL for this PR (updated for commit b3cdacf):

https://pan-dev-f1b58--pr1580-hk1n2tf2.web.app

_{(expires Tue, 17 Nov 2026 22:59:52 GMT)}

_{🔥 via Firebase Hosting GitHub Action 🌎}

_{Sign: 9359a9fa100d5fdb082f75280473a90b1f96eb51}

cnguyen1-panw · 2026-11-10T22:11:56Z

+  /iot/pub/v1/organization:
+    get:
+      description: "Retrieve the organization hierarchy as one list: the top-level group (named after the tenant), its groups and subgroups, and the sites in each group, as shown on the Sites page of the Device Security GUI. <br/> Each node has its `name`, its `type` (`root`, `group` or `site`), the name of its `parent` group, and its `path` (the names from the top-level group down to the node). For a site, `name` is the site's `external_id`, the value shown as \"Name\" in the GUI. <br/> Nodes are listed depth first, and the groups and sites under each parent are sorted by name. Sites that are not in any group are listed under the top-level group, and groups without sites are included. Only the groups and sites your account can access are returned; the top-level group is always returned. <br/> Use `group` to get one group and everything beneath it, and `type` to keep one kind of node. An unknown query parameter returns HTTP 400. <br/> For customers using the IoT Standalone Portal, refer to IoT Standalone Public API Authentication page."
+      operationId: get-organization


for operationId values, please follow the convention of [feature]-[method] so that all API methods for a given feature appear together in the docs nav. I'll sync with Arun to get the rest of the API docs standardized

e.g. organization-get, organization-groups-create, organization-group-update, etc.

Done, thanks!

cnguyen1-panw · 2026-11-10T23:01:07Z

@@ -0,0 +1,41 @@
+parameters:
+  - description: >-
+      Name of the group to delete. Exact, case-sensitive match on the group


Specify if subgroups will be deleted or if subgroups would be moved up a level in the hierarchy.

Done, thanks!

cnguyen1-panw · 2026-11-10T23:01:27Z

+      type: string
+responses:
+  '200':
+    description: Group Successfully Deleted


If sub-groups of a group would also be deleted, this should be "Groups Successfully Deleted"

Only one group is deleted. Its subgroups are not deleted; they move to the parent group. So I kept "Group Successfully Deleted". I also added this to the parameter description.

cnguyen1-panw · 2026-11-10T23:06:04Z

+          $ref: '../../components/examples.yaml#/examples/MoveOrganizationGroupPayloadExample'
+responses:
+  '200':
+    description: Group Successfully Updated


If this can update multiple groups, then "Groups Successfully Updated"

This API updates one group per request, so I kept "Group Successfully Updated".

cnguyen1-panw · 2026-11-10T23:16:57Z

-                parent site. `null` when the site is not in any group.
+                parent site. `null` when the site is not in any group; such a
+                site sits directly under the top-level group, which is how the
+                Device Security GUI and `GET /iot/pub/v1/organization` show it.


Make this a link to the /organization API page if it exstis.

Done, thanks!

cnguyen1-panw · 2026-11-10T23:29:12Z

+      responses:
+        $ref: "api/public/createOrganizationGroup.yaml#/responses"
+    put:
+      description: "Rename one group, move it under another group, or both. The group keeps its subgroups and sites, and a move takes them along. <br/> Groups are identified by name, so renaming a group changes the name that scripts and integrations must use for it. <br/> The top-level group cannot be renamed or moved. A move that would place a group under itself or one of its subgroups, or make the hierarchy deeper than five levels (counting the top-level group), returns HTTP 400. If another request moves a group at the same time and the two moves conflict, the request returns HTTP 400 without making a change; retry it. <br/> For customers using the IoT Standalone Portal, refer to IoT Standalone Public API Authentication page."


Remove the line about the old IoT portal

Done, thanks!

cnguyen1-panw · 2026-11-10T23:29:29Z

+      responses:
+        $ref: "api/public/updateOrganizationGroup.yaml#/responses"
+    delete:
+      description: "Delete one group. Its subgroups and sites are not deleted: they move to the deleted group's parent group. Sites that move to the top-level group are no longer in any group. No site or device data is removed. <br/> The top-level group cannot be deleted. <br/> For customers using the IoT Standalone Portal, refer to IoT Standalone Public API Authentication page."


Remove the line about the old IoT portal

Done, thanks!

cnguyen1-panw · 2026-11-10T23:32:40Z

+
+  /iot/pub/v1/organization/sites:
+    post:
+      description: "Assign up to 1000 sites to a group, by site name (`external_id`). A site belongs to one group, so each site is moved out of the group it was in. Assigning sites to the top-level group removes them from their groups. <br/> If the group or any of the sites does not exist, the request returns HTTP 400, names what is missing, and changes nothing. <br/> For customers using the IoT Standalone Portal, refer to IoT Standalone Public API Authentication page."


Remove the line about the old IoT portal

Done, thanks!

cnguyen1-panw · 2026-11-10T23:33:22Z

+      responses:
+        $ref: "api/public/updateOrganizationGroup.yaml#/responses"
+    delete:
+      description: "Delete one group. Its subgroups and sites are not deleted: they move to the deleted group's parent group. Sites that move to the top-level group are no longer in any group. No site or device data is removed. <br/> The top-level group cannot be deleted. <br/> For customers using the IoT Standalone Portal, refer to IoT Standalone Public API Authentication page."


"...Its subgroups and sites are not deleted; the move to the deleted group's parent group. ..."

(i.e. use a semi-colon instead of a colon)

Done, thanks!

cnguyen1-panw · 2026-11-10T23:33:32Z

+      responses:
+        $ref: "api/public/assignOrganizationSites.yaml#/responses"
+    delete:
+      description: "Remove up to 1000 sites from a group, by site name (`external_id`). The sites then sit directly under the top-level group. The request takes a JSON body, like the assign request. <br/> Every site must currently be in that group. Otherwise the request returns HTTP 400, names the sites that are not in the group, and changes nothing. <br/> For customers using the IoT Standalone Portal, refer to IoT Standalone Public API Authentication page."


Remove the line about the old IoT portal.

Done, thanks!

cnguyen1-panw · 2026-11-10T23:46:02Z

+      ver:
+        type: string
+        description: 'The version of the IoT Security API'
+        example: 'v4.0'


Just to check, do we have a v4? I think the examples should only use a version that we have/support

Yes. The API returns "ver": "v4.0" in every response. The other IoT API examples on pan.dev use the same value.

- Name the operationIds [feature]-[method] (organization-get, organization-groups-create, organization-group-update, organization-group-delete, organization-sites-assign, organization-sites-unassign) so the pages sit together in the docs nav - Remove the IoT Standalone Portal sentence from the six descriptions - Say "Device Security web interface" instead of "GUI" - State on the delete `group` parameter that subgroups and sites move to the parent group - Spell out the name rules on the update request instead of pointing to the create request; say "the following characters" - Link Get Organization Hierarchy from the Get Site `group` description Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

TomorrowMC requested a review from a team as a code owner November 9, 2026 20:20

TomorrowMC deployed to default November 9, 2026 20:20 — with GitHub Actions Active

joey-nolan-panw approved these changes Nov 9, 2026

View reviewed changes

TomorrowMC deployed to preview November 10, 2026 22:57 — with GitHub Actions Active

cnguyen1-panw reviewed Nov 10, 2026

View reviewed changes

TomorrowMC requested a deployment to default November 11, 2026 01:23 — with GitHub Actions Waiting

Conversation

TomorrowMC commented Nov 9, 2026

Uh oh!

joey-nolan-panw left a comment

Choose a reason for hiding this comment

Uh oh!

TomorrowMC commented Nov 10, 2026

Uh oh!

github-actions Bot commented Nov 10, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This branch is waiting to be deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants