Palo Alto Networks Cloud Dynamic User Groups API
The Cloud Dynamic User Groups API from Palo Alto Networks — 4 operation(s) for cloud dynamic user groups.
OpenAPI Specification
openapi: 3.2.0
info:
title: CIE - Cloud Dynamic User Group CRUD Operations APIs Mounted on Strata Cloud Manager Cloud Dynamic User Groups API
version: 1.0.0
description: 'Cloud Dynamic User Groups (CDUG) API for managing dynamic user groups in the Directory Sync Service.
This API provides endpoints for creating, updating, retrieving, and deleting Cloud Dynamic User Groups,
as well as fetching categories and user attribute values.
**All endpoints require SCM JWT access token** and operate within the context of a tenant (TSG). This Open API spec file was created on April 15, 2026. © 2026 Palo Alto Networks, Inc. Palo Alto Networks is a registered trademark of Palo Alto Networks. A list of our trademarks can be found at [https://www.paloaltonetworks.com/company/trademarks.html](https://www.paloaltonetworks.com/company/trademarks.html). All other marks mentioned herein may be trademarks of their respective companies.'
tags:
- name: Cloud Dynamic User Groups
paths:
/directory-sync/v1/cloud-dug-definition/category:
get:
summary: Retrieve Dynamic Group Categories
description: 'Fetches all available categories in a domain along with their context attributes.
This is the **first Application Programming Interface** customers should call to understand what categories are available
and what context attributes can be used to create dynamic user groups.
The returned context attributes can then be used with the `/user-attr-values` endpoint
to get valid values for each attribute.'
operationId: GetDirectory-syncV1Cloud-dug-definitionCategory
responses:
'200':
description: Successfully retrieved categories with their context attributes
content:
application/json:
schema:
type: object
properties:
values:
type: array
items:
$ref: '#/components/schemas/CategoryWithAttributes'
example:
values:
- category: Attribute Based
context attributes:
- UserAccountControl
- Department
- Location
- Country
- Title
- onPremisesSecurityIdentifier
- Manager
- Given Name
- Sur Name
- CompanyName
- EmployeeId
- FaxNumber
- IsResourceAccount
- MobilePhone
- OnPremisesSamAccountName
- OnPremisesDistinguishedName
- OnPremisesExtensionAttributes
- OnPremisesImmutableId
- OnPremisesProvisioningErrors
- OnPremisesSyncEnabled
- onPremisesUserPrincipalName
- OnPremisesDomainName
- PasswordProfile
- PostalCode
- PreferredLanguage
- State
- StreetAddress
- UsageLocation
- UserType
description: Grouping based on the common user attributes
- category: On Demand Assignment
context attributes: []
description: Group members assigned manually
'400':
$ref: '#/components/responses/400_bad_request'
'401':
$ref: '#/components/responses/401_unauthorized'
'404':
description: No categories found
content:
application/json:
schema:
type: object
example: {}
'500':
$ref: '#/components/responses/500_internal_error'
parameters:
- name: domain
in: query
description: Domain name (similar to the Directory Name on the CIE UI e.g., uppercasedss.onmicrosoft.com, okta-directory)
required: true
schema:
type: string
example: uppercasedss.onmicrosoft.com
tags:
- Cloud Dynamic User Groups
/directory-sync/v1/user-attr-values:
get:
summary: Retrieve User Attribute Values
description: 'Fetches all unique values for a specific user attribute in a domain.
**This is the second Application Programming Interface** customers should call after getting categories. Use the
context attributes returned from `/cloud-dug-definition/category` to query this endpoint
and get the valid values for each attribute. These values can then be used when creating
dynamic user groups.'
operationId: GetDirectory-syncV1User-attr-values
responses:
'200':
description: Successfully retrieved attribute values
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
description: Indicates if the request was successful
result:
type: object
properties:
values:
type: array
items:
type: string
description: Array of unique values for the specified attribute
examples:
userAccountControlValues:
summary: UserAccountControl attribute values
value:
success: true
result:
values:
- '512'
departmentValues:
summary: Department attribute values
value:
success: true
result:
values:
- Engineering
- Sales
- Marketing
- HR
- Finance
locationValues:
summary: Location attribute values
value:
success: true
result:
values:
- New York
- San Francisco
- London
- Tokyo
'400':
$ref: '#/components/responses/400_bad_request'
'401':
$ref: '#/components/responses/401_unauthorized'
'500':
$ref: '#/components/responses/500_internal_error'
parameters:
- name: domain
in: query
description: Domain name (same as used in category endpoint)
required: true
schema:
type: string
example: okta-directory
- name: attrName
in: query
description: Attribute name to get values for (must be one of the context attributes returned from category endpoint)
required: true
schema:
type: string
example: UserAccountControl
- name: riskSourceId
in: query
description: Risk source ID for filtering
required: false
schema:
type: string
example: rs-123
tags:
- Cloud Dynamic User Groups
/directory-sync/v1/cloud-dug-definition:
post:
summary: Create Cloud Dynamic User Groups
description: "Creates new dynamic user groups in a domain based on user attribute constraints.\n\n**This is the third Application Programming Interface** in the workflow after getting categories and attribute values.\n\n## Workflow Context\n1. First, call GET `/cloud-dug-definition/category?domain=<domain>` to get available categories and context attributes\n2. Then, call GET `/user-attr-values?domain=<domain>&attrName=<attribute>` for each context attribute to get valid values\n3. Finally, use this POST endpoint to create groups using the category name and attribute values from steps 1 and 2\n\n## Request Body Details\n- **domain**: The domain name (same as used in previous Application Programming Interface calls)\n- **useNormalizedAttrs**: Must be set to `\"true\"` for external Application Programming Interface calls (SCM integration)\n- **value.category**: Category name obtained from the GET category endpoint (e.g., \"Attribute Based\", \"On Demand Assignment\")\n- **value.groups**: Array of groups to create\n - **Name**: The base name for the group (system will append \"_cdug\" suffix automatically)\n - **description**: Optional description for the group\n - **user_attribute_constrain**: Defines the criteria for dynamic group membership\n - Use `$and` operator when ALL conditions must be met\n - Use `$or` operator when ANY condition must be met\n - Attribute names must be from the context attributes list\n - Attribute values must be from the values returned by `/user-attr-values` endpoint\n\n**Note:** The system automatically appends \"_cdug\" suffix to the group."
operationId: PostDirectory-syncV1Cloud-dug-definition
responses:
'200':
description: Successfully created dynamic group(s)
content:
application/json:
schema:
$ref: '#/components/schemas/GroupCreateResponse'
example:
success: true
result:
category: Attribute Based
groups:
- Common-Name: test_123_cdug
Distinguished Name: CN=test_123_cdug,CN=Attribute Based,CN=CDUG,DC=okta-directory
Name: test_123_cdug
Object Class:
- group
WhenChanged: 20260323224204.0Z
cdug_status: created
created: 20260323224204.0Z
createdDateTime: 20260323224204.0Z
description: ''
ext_gtype: 20
ext_lastmod: 1774305724.180538
ext_type: 3
groupTypes: CloudDUG
name: test_123_cdug
objectGUID: 83a1cf1a-2709-11f1-b6ac-22edd0e18ff6
user_attribute_constrain:
$and:
- UserAccountControl: '512'
'400':
$ref: '#/components/responses/400_bad_request'
'401':
$ref: '#/components/responses/401_unauthorized'
'500':
$ref: '#/components/responses/500_internal_error'
parameters: []
tags:
- Cloud Dynamic User Groups
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupCreateRequest'
examples:
createSingleGroup:
summary: Create a single dynamic group with UserAccountControl constraint
value:
domain: okta-directory
useNormalizedAttrs: 'true'
value:
category: Attribute Based
groups:
- Name: test_123
description: ''
user_attribute_constrain:
$and:
- UserAccountControl: '512'
createMultipleConstraints:
summary: Create group with multiple AND constraints
value:
domain: uppercasedss.onmicrosoft.com
useNormalizedAttrs: 'true'
value:
category: Attribute Based
groups:
- Name: engineering_active_users
description: Active users in Engineering department
user_attribute_constrain:
$and:
- UserAccountControl: '512'
- Department: Engineering
createWithOrConstraints:
summary: Create group with OR constraints
value:
domain: okta-directory
useNormalizedAttrs: 'true'
value:
category: Attribute Based
groups:
- Name: sales_or_marketing
description: Users in Sales or Marketing
user_attribute_constrain:
$or:
- Department: Sales
- Department: Marketing
/directory-sync/v1/cloud-dug-definition/group:
get:
summary: Retrieve Cloud Dynamic User Groups
description: 'Fetches dynamic user groups by domain or aggregationId with support for filtering and pagination.
**Note:** Set `useNormalizedAttrs` to `"true"` for external Application Programming Interface calls (SCM integration).
## Usage Patterns
### 1. List all groups in a domain (with pagination)
```
GET /cloud-dug-definition/group?domain=okta-directory&useNormalizedAttrs=true&pageNum=1&pageSz=10
```
This returns all CDUG groups with pagination. From this response, you can extract:
- `defID` - Category identifier for filtering groups by category
- `objectGUID` - Unique group identifier for fetching/updating/deleting a specific group
### 2. Get a specific group by objectGUID
After creating a group via POST, you receive an `objectGUID` in the response. Use it to fetch that specific group:
```
GET /cloud-dug-definition/group?domain=okta-directory&objectGUID=83a1cf1a-2709-11f1-b6ac-22edd0e18ff6&useNormalizedAttrs=true
```
### 3. Get all groups in a specific category
First, call GET groups to see all groups and their `defID` values. Then filter by category:
```
GET /cloud-dug-definition/group?domain=okta-directory&defID=116c2d28-0cfb-11f1-a8d8-d2bbfe9d4496&useNormalizedAttrs=true
```
This returns only groups belonging to that category (e.g., "Attribute Based").'
operationId: GetDirectory-syncV1Cloud-dug-definitionGroup
responses:
'200':
description: Successfully retrieved dynamic groups with pagination information
content:
application/json:
schema:
$ref: '#/components/schemas/GroupListResponse'
example:
count: 10
pageNum: 1
pageSz: 10
remains: 2
value:
- Common-Name: test_cdug
Distinguished Name: CN=test_cdug,CN=Attribute Based,CN=CDUG,DC=panwssfdev-preview,DC=oktapreview,DC=com
Name: test_cdug
Object Class:
- group
WhenChanged: 20260318211709.0Z
_id: 69bb1655a0708397b1188640
category: Attribute Based
cdug_status: deployed
created: 20260318211709.0Z
createdDateTime: 20260318211709.0Z
defID: 116c2d28-0cfb-11f1-a8d8-d2bbfe9d4496
description: ''
ext_gtype: 20
ext_lastmod: 1773868629.963407
ext_type: 3
groupTypes: CloudDUG
name: test_cdug
objectGUID: d32d355e-230f-11f1-841b-5a9eb7df464d
user_attribute_constrain:
$and:
- UserAccountControl: '512'
- Common-Name: test2_cdug
Distinguished Name: CN=test2_cdug,CN=Attribute Based,CN=CDUG,DC=okta-directory
Name: test2_cdug
Object Class:
- group
WhenChanged: 20260318211754.0Z
_id: 69bb1682d5598d891455090f
category: Attribute Based
cdug_status: deployed
created: 20260318211754.0Z
createdDateTime: 20260318211754.0Z
defID: 116c2d28-0cfb-11f1-a8d8-d2bbfe9d4496
description: ''
ext_gtype: 20
ext_lastmod: 1773868674.6279
ext_type: 3
groupTypes: CloudDUG
name: test2_cdug
objectGUID: edcc7924-230f-11f1-a969-0ae740b4098b
user_attribute_constrain:
$and:
- Department:
$options: i
$regex: ^a
'400':
$ref: '#/components/responses/400_bad_request'
'401':
$ref: '#/components/responses/401_unauthorized'
'404':
description: No groups found
content:
application/json:
schema:
type: object
example: {}
'500':
$ref: '#/components/responses/500_internal_error'
parameters:
- name: domain
in: query
description: Domain name (required if aggregationId not provided)
required: false
schema:
type: string
example: okta-directory
- name: aggregationId
in: query
description: Aggregation ID to fetch groups across risk sources (required if domain not provided)
required: false
schema:
type: string
example: agg-123
- name: objectGUID
in: query
description: 'Group unique identifier to fetch a specific group.
You receive this in the response when creating a group via POST /cloud-dug-definition.
Use this to retrieve, update, or delete a specific group.
'
required: false
schema:
type: string
example: 83a1cf1a-2709-11f1-b6ac-22edd0e18ff6
- name: defID
in: query
description: 'Category identifier to fetch all groups in a specific category.
To get the defID, first call this GET endpoint without filters to see all groups and their defID values.
Then use the defID to filter groups by category (e.g., all "Attribute Based" groups).
'
required: false
schema:
type: string
example: 116c2d28-0cfb-11f1-a8d8-d2bbfe9d4496
- name: useNormalizedAttrs
in: query
description: Must be set to "true" for external API calls (SCM integration)
required: true
schema:
type: string
enum:
- 'true'
example: 'true'
- name: pageNum
in: query
description: Page number (starts at 1). Use with pageSz for pagination.
required: false
schema:
type: integer
minimum: 1
example: 1
- name: pageSz
in: query
description: Number of items per page (max 1000)
required: false
schema:
type: integer
minimum: 1
maximum: 1000
example: 10
tags:
- Cloud Dynamic User Groups
put:
summary: Update Cloud Dynamic User Groups
description: "Updates an existing Cloud Dynamic User Group. Use this endpoint to modify group attributes\nand constraints for an already created group.\n\n**This is used to edit an existing/created group.**\n\n## How it Works\n- The `objectGUID` in the request body identifies which group to update\n- The `objectGUID` is obtained from:\n - POST `/cloud-dug-definition` response when creating a group\n - GET `/cloud-dug-definition/group` response when listing groups\n- Only the fields you want to update need to be included in the request\n- Primary use case: updating `user_attribute_constrain` to modify group membership criteria\n\n## Important Behavior\n**The Application Programming Interface returns HTTP 200 even when the objectGUID is not found.**\nWhen the provided objectGUID doesn't exist, the response will be:\n```json\n{\n \"success\": true,\n \"result\": {\n \"sync\": \"Not found cloud dug def group guid <objectGUID>\",\n \"value\": \"\"\n }\n}\n```\nAlways check the `result.sync` field for error messages when processing the response.\n\n**Note:** Set `useNormalizedAttrs` to `\"true\"` for external Application Programming Interface calls (SCM integration). Also, we do not allow the update of name related attributes (Name, Common-Name, Distinguished Name). This is also to match behavior of UI."
operationId: PutDirectory-syncV1Cloud-dug-definitionGroup
responses:
'200':
description: 'Response from update operation.
**Note:** The API returns HTTP 200 even when the objectGUID is not found.
Check the `result.sync` field for error messages like "Not found cloud dug def group guid".
'
content:
application/json:
schema:
$ref: '#/components/schemas/GroupUpdateResponse'
examples:
successfulUpdate:
summary: Successfully updated group
value:
success: true
result:
objectGUID: 72bbc29c-2703-11f1-b839-22edd0e18ff6
Mail: ''
WhenChanged: 20260325044739.0Z
cdug_status: updated
description: ''
ext_lastmod: 1774414059.086046
user_attribute_constrain:
$and:
- State: CA
groupNotFound:
summary: ObjectGUID not found (still returns 200)
value:
success: true
result:
sync: Not found cloud dug def group guid 72bbc29c-2703-11f1-b839-22edd0e18ff61
value: ''
'400':
$ref: '#/components/responses/400_bad_request'
'401':
$ref: '#/components/responses/401_unauthorized'
'500':
$ref: '#/components/responses/500_internal_error'
parameters: []
tags:
- Cloud Dynamic User Groups
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupUpdateRequest'
examples:
updateConstraints:
summary: Update group attribute constraints
value:
domain: okta-directory
useNormalizedAttrs: 'true'
value:
objectGUID: 72bbc29c-2703-11f1-b839-22edd0e18ff6
description: ''
user_attribute_constrain:
$and:
- State: CA
updateWithMail:
summary: Update group with additional fields
value:
domain: okta-directory
useNormalizedAttrs: 'true'
value:
objectGUID: 72bbc29c-2703-11f1-b839-22edd0e18ff6
Name: updated_group_name
Mail: ''
description: Updated description for the group
user_attribute_constrain:
$and:
- UserAccountControl: '512'
- Department: Engineering
updateMultipleConstraints:
summary: Update with multiple OR constraints
value:
domain: uppercasedss.onmicrosoft.com
useNormalizedAttrs: 'true'
value:
objectGUID: d32d355e-230f-11f1-841b-5a9eb7df464d
description: Sales or Marketing users
user_attribute_constrain:
$or:
- Department: Sales
- Department: Marketing
delete:
summary: Delete Cloud Dynamic User Groups
description: 'Deletes a specific Cloud Dynamic User Group by objectGUID or all groups in a category by defID.
## How it Works
- Use `objectGUID` to delete a specific group (obtained from POST create or GET list responses)
- Use `defID` to delete all groups in a category (obtained from GET list response)
- Provide either `objectGUID` or `defID`, but not both
## Important Behavior
**The Application Programming Interface returns HTTP 200 even when deletion fails or is delayed.**
### Possible scenarios:
1. **Sync in progress**: If a data sync is currently running for the tenant, the deletion request is saved but not immediately executed. You''ll need to retry later or wait for the next sync.
2. **Successful deletion**: The group is deleted immediately and sync is scheduled.
Always check the `result.sync` and `result.detail` fields to determine the actual outcome:
- `"sync": "success"` - Deletion completed
- `"sync": "Cloud Dynamic Group definition saved..."` + `"detail": "Data sync in-progress..."` - Deletion pending, retry later.'
operationId: DeleteDirectory-syncV1Cloud-dug-definitionGroup
responses:
'200':
description: 'Delete request processed (does not guarantee immediate deletion).
**Important:** HTTP 200 does not mean the group was deleted. Check the response body:
- If `result.sync` = "success", deletion completed
- If `result.detail` contains "Data sync in-progress", deletion is pending and group was NOT deleted yet
'
content:
application/json:
schema:
$ref: '#/components/schemas/GroupDeleteResponse'
examples:
successfulDeletion:
summary: Group successfully deleted
value:
success: true
result:
sync: success
value: null
syncInProgress:
summary: Sync in progress - deletion pending (group NOT deleted yet)
value:
success: true
result:
detail: Data sync in-progress for customer 4231344437556610560, Please reschedule later
sync: Cloud Dynamic Group definition saved. Unable to schedule sync. Try to sync changes manually or wait for the next automated sync
value: null
'400':
$ref: '#/components/responses/400_bad_request'
'401':
$ref: '#/components/responses/401_unauthorized'
'500':
$ref: '#/components/responses/500_internal_error'
parameters:
- name: domain
in: query
description: Domain name (same as used when creating the group)
required: true
schema:
type: string
example: okta-directory
- name: objectGUID
in: query
description: 'Unique group identifier to delete a specific group.
Obtained from POST /cloud-dug-definition response or GET /cloud-dug-definition/group response.
Provide either objectGUID or defID, but not both.
'
required: false
schema:
type: string
example: 72bbc29c-2703-11f1-b839-22edd0e18ff6
- name: defID
in: query
description: 'Category identifier to delete all groups in a specific category.
Obtained from GET /cloud-dug-definition/group response.
Provide either objectGUID or defID, but not both.
'
required: false
schema:
type: string
example: 116c2d28-0cfb-11f1-a8d8-d2bbfe9d4496
tags:
- Cloud Dynamic User Groups
components:
schemas:
CategoryWithAttributes:
type: object
description: Category definition with available context attributes
properties:
category:
type: string
description: Category name
example: Attribute Based
context attributes:
type: array
description: List of user attributes that can be used to create groups in this category
items:
type: string
example:
- UserAccountControl
- Department
- Location
- Country
- Title
description:
type: string
description: Description of what this category is used for
example: Grouping based on the common user attributes
GroupCreateRequest:
type: object
required:
- domain
- value
- useNormalizedAttrs
properties:
domain:
type: string
description: Domain name (e.g., okta-directory, uppercasedss.onmicrosoft.com)
example: okta-directory
useNormalizedAttrs:
type: string
enum:
- 'true'
description: Must be set to "true" for external API calls (SCM integration)
example: 'true'
value:
type: object
required:
- category
- groups
properties:
category:
type: string
description: Category name obtained from GET /cloud-dug-definition/category endpoint
example: Attribute Based
groups:
type: array
description: Array of groups to create (can create multiple groups in a single request)
items:
type: object
required:
- Name
- user_attribute_constrain
properties:
Name:
type: string
description: Base name for the group (system automatically appends "_cdug" suffix)
example: test_123
description:
type: string
description: Optional description for the group
example: Active users with standard account control
user_attribute_constrain:
type: object
description: 'Defines the criteria for dynamic group membership.
Use $and when ALL conditions must match, or $or when ANY condition must match.
Attribute names must be from the context attributes list from GET /category endpoint.
Attribute values must match values from GET /user-attr-values endpoint.
'
properties:
$and:
type: array
description: All conditions must be true for a user to be included in the group
items:
type: object
additionalProperties:
type: string
$or:
type: array
description: Any condition must be true for a user to be included in the group
items:
type: object
additionalProperties:
type: string
example:
$and:
- UserAccountControl: '512'
GroupDeleteResponse:
type: object
description: 'Response from deleting Cloud Dynamic User Group(s).
**Important:** HTTP 200 does not guarantee the group was deleted.
Check the response fields to determine the actual outcome.
'
properties:
success:
type: boolean
description: Indicates if the request was processed (does not mean deletion completed)
example: true
result:
type: object
description: 'Contains deletion status information.
Check `sync` field to determine if deletion completed or is pending.
'
properties:
sync:
type: string
description: 'Deletion status indicator:
- "success" - Group was successfully deleted
- "Cloud Dynamic Group definition saved. Unable to schedule sync..." - Deletion is pending due to sync in progress
'
enum:
- success
- Cloud Dynamic Group definition saved. Unable to schedule sync. Try to sync changes manually or wait for the next automated sync
example: success
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/palo-alto-networks/refs/heads/main/openapi/palo-alto-networks-cloud-dynamic-user-groups-api-openapi.yml