Palo Alto Networks Directory Sync Service API

openapi: 3.2.0
info:
  title: Palo Alto Networks Directory Sync Service API
  version: '1.0'
  description: 'Operations tagged Directory Sync Service across 3 of this provider''s published API definitions: palo-alto-cloud-identity-engine-api-openapi-original.yml, palo-alto-networks-directory-sync-service-api-openapi.yml, palo-alto-scm-config-ciedss-cie-dss-r2-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.stratacloud.paloaltonetworks.com/aiops/bpa/v1
  description: AIOps for NGFW BPA API production server.
- url: https://api.sase.paloaltonetworks.com
tags:
- name: Directory Sync Service
paths:
  https://api.sase.paloaltonetworks.com/cie/directory-sync/v1/domains:
    get:
      summary: Palo Alto Networks Domain Details
      description: "Retrieves a list of all domains configured for a specific CIE tenant within the Directory Sync Service (DSS). \nThis operation returns details for each of the tenant's configured domains, including its current status, the timestamp of the last successful synchronization, and object counts (such as users and groups)."
      responses:
        '200':
          description: List of all domain metadata
          content:
            application/json:
              example:
                success: true
                result:
                - count:
                    computer: 1
                    container: 117
                    group: 50
                    ou: 1
                    user: 16
                  domain: cyberarktest.com
                  log: []
                  netbios: cyberarktest
                  status:
                    description: cache_applied
                    lastSuccessUpdatedOn: 1737572486
                    statusUpdatedOn: 1737572486
                  sync_duration: 14607313
                  type: Active Directory
        '500':
          description: If CIE Directory Sync Service is down then we see the Internal Service Error
          $ref: '#/components/responses/500_internal_error'
      parameters: []
      tags:
      - Directory Sync Service
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  https://api.sase.paloaltonetworks.com/cie/directory-sync/v1/cache-users:
    post:
      summary: Palo Alto Networks User Information
      description: "Provides user related information for a domain present in Specific CIE tenant.\nThis endpoint supports several use cases by using different request payloads. \nIt also supports pagination to manage large result sets.\n          \n          Use this endpoint to:\n            - **list_all_users_in_domain**: List all users within a specific domain.\n            - **list_specific_users**: Find specific users by filtering on attributes like name or email.\n            - **list_users_in_particular_group**: Get all users who are members of a specific group.\n            - **check_group_membership**: Check if a user is a member of a particular group."
      responses:
        '200':
          description: Returns an array of user objects matching the query.
          content:
            application/json:
              example:
                success: true
                result:
                  count: 1
                  data:
                    domains:
                    - domainName: example.onmicrosoft.com
                      lastSyncTmp: 1760646692
                      netbios: example
                      objects:
                      - Common-Name: Jack Park
                        Country: GERMANY
                        Department: Sales
                        Distinguished Name: CN=Jack,UID=Park,DC=example,DC=com
                        Location: Munich
                        Mail: jackpark@example.com
                        Name: JACK, PARK
                        SAM Account Name: jack.park
                        Unique Identifier: 00009498-94e8-4873-b957-015e9e2587eb
                        User Principal Name: jackpark@example.come
                        WhenChanged: 20230815042928.345954Z
                  pageNum: 1
                  pageSz: 1
                  remains: 50
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  result:
                    type: object
                    properties:
                      count:
                        type: integer
                      pageNum:
                        type: integer
                      pageSz:
                        type: integer
                      remains:
                        type: integer
                      data:
                        type: array
                        items:
                          type: object
        '400':
          $ref: '#/components/responses/400_bad_request'
        '500':
          $ref: '#/components/responses/500_internal_error'
      parameters: []
      tags:
      - Directory Sync Service
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/list_all_users_in_domain'
              - $ref: '#/components/schemas/list_specific_users'
              - $ref: '#/components/schemas/list_users_in_particular_group'
              - $ref: '#/components/schemas/check_group_membership'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  https://api.sase.paloaltonetworks.com/cie/directory-sync/v1/cache-groups:
    post:
      summary: Palo Alto Networks Group Information
      description: "Provides group related information for a domain present in a specific CIE tenant. \nThis endpoint supports several use cases by using different request payloads. \nIt also supports pagination to manage large result sets.\n\nUse this endpoint to:\n- **list_all_groups_in_domain**: List all groups within a specific domain.\n- **list_specific_groups**: Find specific groups by filtering on attributes like name.\n- **list_groups_user_belongs_to**: Get all groups that a specific user belongs to.\n- **check_user_in_particular_group**: Check if a group contains a particular user."
      responses:
        '200':
          description: Returns an array of group objects matching the query.
          content:
            application/json:
              example:
                success: true
                result:
                  count: 1
                  data:
                    domains:
                    - domainName: example.onmicrosoft.com
                      lastSyncTmp: 1760648138
                      netbios: example
                      objects:
                      - cn: ADMIN
                        created: 20230117094434.800831Z
                        dn: CN=ADMIN,DC=example,DC=onmicrosoft,DC=com
                        domain: example.onmicrosoft.com
                        groupType: security
                        member: []
                        meta_created: 2023-01-17 09:44:34.800831+00:00
                        meta_lastModified: 2025-08-26 13:26:11.093255+00:00
                        meta_resourceType: Group
                        name: ADMIN
                        objectClass:
                        - group
                        objectGUID: 0087272b-0ea5-4884-8dac-17b1673c1496
                        sAMAccountName: ADMIN
                        topoIndex: 0
                        whenChanged: 20250826132611.093255Z
                  pageNum: 1
                  pageSz: 1
                  remains: 50
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  result:
                    type: object
                    properties:
                      count:
                        type: integer
                      data:
                        type: array
                        items:
                          type: object
        '400':
          $ref: '#/components/responses/400_bad_request'
        '500':
          $ref: '#/components/responses/500_internal_error'
      parameters: []
      tags:
      - Directory Sync Service
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/list_all_groups_in_domain'
              - $ref: '#/components/schemas/list_specific_groups'
              - $ref: '#/components/schemas/list_groups_user_belongs_to'
              - $ref: '#/components/schemas/check_user_in_particular_group'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /cie/directory-sync/v1/domains:
    get:
      summary: Fetch domains from the CIE Directory Sync Service
      description: Retrieve list of all domains and details specific to each of these domains that are configured in the CIE Directory Sync Service.
      responses:
        '200':
          description: List of all domain metadata
          content:
            application/json:
              example:
                success: true
                result:
                - count:
                    computer: 1
                    container: 117
                    group: 50
                    ou: 1
                    user: 16
                  domain: cyberarktest.com
                  log: []
                  netbios: cyberarktest
                  status:
                    description: cache_applied
                    lastSuccessUpdatedOn: 1737572486
                    statusUpdatedOn: 1737572486
                  sync_duration: 14607313
                  type: Active Directory
        '500':
          description: If CIE Directory Sync Service is down then we see the Internal Service Error
          $ref: '#/components/responses/500_internal_error'
      parameters: []
      tags:
      - Directory Sync Service
    servers:
    - url: https://api.sase.paloaltonetworks.com
  /cie/directory-sync/v1/cache-users:
    post:
      summary: Fetch user information from the CIE Directory Sync Service across multiple scenarios.
      description: 'This endpoint retrieves user data from the CIE Directory Sync Service for different scenarios/use-cases. Optional pagination parameters can be used. Choose the payload schema that matches your use case:


        - **list_all_users_in_domain**: Retrieve all users in a domain.

        - **list_specific_users**: Retrieve specific users matching a name-based filter in a domain. Supports filtering of users based on specific attributes and values (similar to the WHERE clause in SQL).

        - **list_users_in_particular_group**: Retrieve users belonging to a specified group, filtered using the group-based filter

        - **check_group_membership**: Check if a specific user belongs to a specified group.'
      responses:
        '200':
          description: Returns an array of user objects matching the query.
          content:
            application/json:
              example:
                success: true
                result:
                  count: 1
                  data:
                    domains:
                    - domainName: example.onmicrosoft.com
                      lastSyncTmp: 1760646692
                      netbios: example
                      objects:
                      - Common-Name: Jack Park
                        Country: GERMANY
                        Department: Sales
                        Distinguished Name: CN=Jack,UID=Park,DC=example,DC=com
                        Location: Munich
                        Mail: jackpark@example.com
                        Name: JACK, PARK
                        SAM Account Name: jack.park
                        Unique Identifier: 00009498-94e8-4873-b957-015e9e2587eb
                        User Principal Name: jackpark@example.come
                        WhenChanged: 20230815042928.345954Z
                  pageNum: 1
                  pageSz: 1
                  remains: 50
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  result:
                    type: object
                    properties:
                      count:
                        type: integer
                      pageNum:
                        type: integer
                      pageSz:
                        type: integer
                      remains:
                        type: integer
                      data:
                        type: array
                        items:
                          type: object
        '400':
          $ref: '#/components/responses/400_bad_request'
        '500':
          $ref: '#/components/responses/500_internal_error'
      parameters: []
      tags:
      - Directory Sync Service
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/list_all_users_in_domain'
              - $ref: '#/components/schemas/list_specific_users'
              - $ref: '#/components/schemas/list_users_in_particular_group'
              - $ref: '#/components/schemas/check_group_membership'
    servers:
    - url: https://api.sase.paloaltonetworks.com
  /cie/directory-sync/v1/cache-groups:
    post:
      summary: Fetch group information from the CIE Directory Sync Service across multiple scenarios.
      description: 'This endpoint retrieves group data from the CIE Directory Sync Service under various conditions. Optional pagination parameters can be used. Choose the payload schema that matches your use case:


        - **list_all_groups_in_domain**: Retrieve all groups in a domain.

        - **list_specific_groups**: Retrieve specific groups matching a name-based filter. Supports filtering of groups based on specific attributes and values (similar to the WHERE clause in SQL).

        - **list_groups_user_belongs_to**: Retrieve all groups containing specific users based on user-filter

        - **check_user_in_particular_group**: Check if a specific group has a particular user in it, filtered using attribute-based filter (to filter the user) and group-based filter (to filter the group).'
      responses:
        '200':
          description: Returns an array of group objects matching the query.
          content:
            application/json:
              example:
                success: true
                result:
                  count: 1
                  data:
                    domains:
                    - domainName: example.onmicrosoft.com
                      lastSyncTmp: 1760648138
                      netbios: example
                      objects:
                      - cn: ADMIN
                        created: 20230117094434.800831Z
                        dn: CN=ADMIN,DC=example,DC=onmicrosoft,DC=com
                        domain: example.onmicrosoft.com
                        groupType: security
                        member: []
                        meta_created: 2023-01-17 09:44:34.800831+00:00
                        meta_lastModified: 2025-08-26 13:26:11.093255+00:00
                        meta_resourceType: Group
                        name: ADMIN
                        objectClass:
                        - group
                        objectGUID: 0087272b-0ea5-4884-8dac-17b1673c1496
                        sAMAccountName: ADMIN
                        topoIndex: 0
                        whenChanged: 20250826132611.093255Z
                  pageNum: 1
                  pageSz: 1
                  remains: 50
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  result:
                    type: object
                    properties:
                      count:
                        type: integer
                      data:
                        type: array
                        items:
                          type: object
        '400':
          $ref: '#/components/responses/400_bad_request'
        '500':
          $ref: '#/components/responses/500_internal_error'
      parameters: []
      tags:
      - Directory Sync Service
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/list_all_groups_in_domain_2'
              - $ref: '#/components/schemas/list_specific_groups'
              - $ref: '#/components/schemas/list_groups_user_belongs_to_2'
              - $ref: '#/components/schemas/check_user_in_particular_group_2'
    servers:
    - url: https://api.sase.paloaltonetworks.com
  /cie/directory-sync/v1/connection/update-secret:
    post:
      summary: Update directory connection client secret
      description: 'Updates the client secret for an existing directory connection using the Client Credential Flow (CCF) in the CIE Directory Sync Service.


        The tenant is automatically identified from the JWT token in the request.'
      responses:
        '200':
          description: Secret updated successfully
          content:
            application/json:
              example:
                success: true
                result: true
        '400':
          $ref: '#/components/responses/400_bad_request'
        '404':
          description: Directory not found
          content:
            application/json:
              example:
                success: true
                result:
                  error:
                    error-message: Directory b7e3a1f4-2c9d-4e6b-8a05-d3f7c2e91b40 not found
        '421':
          description: Invalid provider value
          content:
            application/json:
              example:
                success: true
                result:
                  error:
                    error-message: 'provider must be one of: aad, aad_gov, aad_cn, okta'
        '500':
          $ref: '#/components/responses/500_internal_error'
      parameters: []
      tags:
      - Directory Sync Service
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - directoryId
              - provider
              - client_secret
              properties:
                directoryId:
                  type: string
                  description: The unique identifier of the directory connection to update
                  example: b7e3a1f4-2c9d-4e6b-8a05-d3f7c2e91b40
                provider:
                  type: string
                  description: The directory provider type
                  enum:
                  - aad
                  - aad_gov
                  - aad_cn
                  - okta
                  example: aad
                client_secret:
                  type: string
                  description: The new client secret to set for the directory connection
                  example: my-new-client-secret
    servers:
    - url: https://api.sase.paloaltonetworks.com
components:
  schemas:
    attr_based_filter:
      type: object
      description: Attribute-based filter.
      required:
      - attrName
      - attrValue
      - match
      properties:
        attrName:
          description: Attribute name
          type: string
          enum:
          - User Principal Name
          - Common-Name
          - Name
          - Distinguished Name
          - SAM Account Name
          - Unique Identifier
          example: Distinguished Name
        attrValue:
          description: Attribute value
          type: string
          example: CN=Jack,UID=Park,DC=example,DC=com
        match:
          description: Value you want to match.
          type: string
          enum:
          - equal
          - textSearch
          example: equal
    check_group_membership:
      description: Check if a specific user belongs to a particular group, filtered using attribute-based filter (to filter the user) and group-based filter (to filter the group)
      allOf:
      - $ref: '#/components/schemas/list_users_in_particular_group'
      required:
      - name
      properties:
        name:
          $ref: '#/components/schemas/attr_based_filter'
      example:
        domain: paloaltonetworks.com
        filter:
          type: group
          name:
            attrName: Common-Name
            attrValue: Admins
            match: equal
          level: recursive
        name:
          attrName: User Principal Name
          attrValue: carol@paloaltonetworks.com
          match: equal
    list_all_users_in_domain:
      description: Retrieve all users in a domain.
      allOf:
      - $ref: '#/components/schemas/domain_param'
      - $ref: '#/components/schemas/pagination_params'
      properties:
        attrs:
          type: array
          description: User attributes included as part of the response.
          items:
            type: string
          example:
          - Common-Name
          - Mail
          - Unique Identifier
          - Manager
          - User Principal Name
          - Name
          - Distinguished Name
          - SAM Account Name
        useNormalizedAttrs:
          type: string
          enum:
          - 'True'
          - 'False'
          example: 'True'
      example:
        domain: paloaltonetworks.com
        attrs:
        - Common-Name
        - Unique Identifier
        - Name
        - Distinguished Name
        - SAM Account Name
        - Department
        - Last Login
        - LastLogonTime
        - Location
        - Mail
        - Manager
        - Title
        - User Principal Name
        - UserAccountControl
        - WhenChanged
        useNormalizedAttrs: 'True'
    list_users_in_particular_group:
      description: Retrieve specific attributes for users belonging to a particular group, filtered using the group-based filter.
      allOf:
      - $ref: '#/components/schemas/domain_param'
      - $ref: '#/components/schemas/pagination_params'
      required:
      - filter
      properties:
        filter:
          $ref: '#/components/schemas/group_filter'
        attrs:
          type: array
          description: user attributes part of the response
          items:
            type: string
          example:
          - Common-Name
          - Mail
          - Unique Identifier
          - Manager
          - User Principal Name
          - Name
          - Distinguished Name
          - SAM Account Name
      example:
        domain: paloaltonetworks.com
        filter:
          type: group
          name:
            attrName: Common-Name
            attrValue: Administrators
            match: equal
          level: recursive
        attrs:
        - Common-Name
        - Mail
        - Unique Identifier
        - Manager
        - User Principal Name
        - Name
        - Distinguished Name
        - SAM Account Name
    pagination_params:
      type: object
      description: Optional pagination parameters.
      properties:
        pageNum:
          type: integer
          description: Page number to retrieve (starting from page 1).
          example: 1
        pageSz:
          type: integer
          description: Number of records per page (max is 1000 per page).
          example: 500
    list_specific_users:
      description: Retrieve specific users matching a name-based filter in a domain. Supports filtering of users based on specific attributes and values (similar to the WHERE clause in SQL).
      allOf:
      - $ref: '#/components/schemas/fetch_all_users_attrs'
      required:
      - name
      properties:
        name:
          $ref: '#/components/schemas/attr_based_filter'
      example:
        domain: paloaltonetworks.com
        name:
          attrName: Distinguished Name
          enum:
          - User Principal Name
          - Common-Name
          - Name
          - Distinguished Name
          - SAM Account Name
          - Unique Identifier
          attrValue: CN=Jack,UID=Park,DC=example,DC=com
          match: equal
        attrs:
        - Common-Name
        - Mail
        - Unique Identifier
        - Manager
        - User Principal Name
        - Name
        - Distinguished Name
        - SAM Account Name
        useNormalizedAttrs: 'True'
    fetch_all_users_attrs:
      description: Retrieve all attributes for a specific user.
      allOf:
      - $ref: '#/components/schemas/domain_param'
      - $ref: '#/components/schemas/pagination_params'
      properties:
        attrs:
          type: array
          description: User attributes included as part of the response.
          items:
            type: string
          example:
          - Common-Name
          - Mail
          - Unique Identifier
          - Manager
          - User Principal Name
          - Name
          - Distinguished Name
          - SAM Account Name
        useNormalizedAttrs:
          description: Use the normalized attribute.
          type: string
          enum:
          - 'True'
          - 'False'
          example: 'True'
      example:
        domain: paloaltonetworks.com
        attrs:
        - Common-Name
        - Mail
        - Unique Identifier
        - Manager
        - User Principal Name
        - Name
        - Distinguished Name
        - SAM Account Name
        useNormalizedAttrs: 'True'
    list_all_groups_in_domain:
      description: Retrieve all groups in a particular domain.
      allOf:
      - $ref: '#/components/schemas/domain_param'
      - $ref: '#/components/schemas/pagination_params'
      required:
      - attrs
      properties:
        attrs:
          type: array
          items:
            type: string
          description: Group attributes included as part of the response.
          example:
          - Common-Name
          - Unique Identifier
          - Name
          - Distinguished Name
          - SAM Account Name
        useNormalizedAttrs:
          type: string
          enum:
          - 'True'
          - 'False'
          example: 'False'
      example:
        domain: paloaltonetworks.com
        pageNum: 1,
        pageSz: 80
    domain_param:
      type: object
      description: Domain name for a specific directory.
      required:
      - domain
      properties:
        domain:
          type: string
          description: Domain name of the target directory.
          example: paloaltonetworks.com
    check_user_in_particular_group:
      description: Check if a specific group has a particular user in it, filtered using attribute-based filter (to filter the group) and group-based filter (to filter the user)
      allOf:
      - $ref: '#/components/schemas/list_all_groups_in_domain'
      required:
      - name
      - filter
      properties:
        name:
          $ref: '#/components/schemas/attr_based_filter'
        filter:
          type: object
          required:
          - type
          - name
          properties:
            type:
              type: string
              enum:
              - user
              example: user
            name:
              $ref: '#/components/schemas/attr_based_filter'
            attrs:
              type: array
              description: group attributes part of the response
              items:
                type: string
              example:
              - Common-Name
              - Unique Identifier
              - Name
              - Distinguished Name
              - SAM Account Name
          example:
            type: user
            name:
              attrName: Distinguished Name
              attrValue: CN=Jack,UID=Park,DC=example,DC=com
              match: equal
            attrs:
            - Common-Name
            - Unique Identifier
            - Name
            - Distinguished Name
            - SAM Account Name
      example:
        domain: paloaltonetworks.com
        filter:
          type: group
          name:
            attrName: Common-Name
            attrValue: Admins
            match: equal
          level: recursive
        name:
          attrName: User Principal Name
          attrValue: carol@paloaltonetworks.com
          match: equal
    group_filter:
      type: object
      description: Group-based filter.
      required:
      - type
      - name
      - level
      properties:
        type:
          type: string
          enum:
          - group
          example: group
        name:
          $ref: '#/components/schemas/attr_based_filter'
        level:
          type: string
          enum:
          - immediate
          - recursive
          example: immediate
    list_groups_user_belongs_to:
      description: Retrieve all groups containing specific users based on user-filter.
      allOf:
      - $ref: '#/components/schemas/domain_param'
      - $ref: '#/components/schemas/pagination_params'
      required:
      - filter
      properties:
        filter:
          type: object
          required:
          - type
          - name
          properties:
            type:
              type: string
              enum:
              - user
              example: user
            name:
              $ref: '#/components/schemas/attr_based_filter'
            attrs:
              type: array
              description: group attributes part of the response
              items:
                type: string
              example:
              - Common-Name
              - Unique Identifier
              - Name
              - Distinguished Name
              - SAM Account Name
          example:
            type: user
            name:
              attrName: Distinguished Name
              attrValue: CN=Jack,UID=Park,DC=example,DC=com
              match: equal
            attrs:
            - Common-Name
            - Unique Identifier
            - Name
            - Distinguished Name
            - SAM Account Name
      example:
        domain: paloaltonetworks.com
        filter:
          type: user
          name:
            attrName: Distinguished Name
            attrValue: CN=Jack,UID=Park,DC=example,DC=com
            enum:
            - User Principal Name
            - Common-Name
            - Name
            - Distinguished Name
            - SAM Account Name
            - Unique Identifier
            match: equal
        attrs:
        - Common-Name
        - Unique Identifier
        - Name
        - Distinguished Name
        - SAM Account Name
        - Department
        - Last Login
        - LastLogonTime
        - Location
        - Mail
        - Manager
        - Title
        - User Principal Name
        - UserAccountControl
        - WhenChanged
    list_specific_groups:
      description: Retrieve specific groups matching a name-based filter. Supports filtering of groups based on specific attributes and values (similar to the WHERE clause in SQL).
      allOf:
      - $ref: '#/components/schemas/list_all_groups_in_domain'
      required:
      - name
      properties:
        name:
          $ref: '#/components/schemas/attr_based_filter'
        attrs:
          type: array
          items:
            type: string
          description: group attributes part of the response
          example:
          - Common-Name
          - Unique Identifier
          - Name
          - Distinguished Name
          - SAM Account Name
      example:
        domain: paloaltonetworks.com
        name:
          attrName: Common-Name
          enum:
          - User Principal Name
          - Common-Name
          - Name
          - Distinguished Name
          - SAM Account Name
          - Unique Identifier
          attrValue: admins
          match: equal
        attrs:
        - Common-Name
        - Unique Identifier
        - Name
        - Distinguished Name
        - SAM Account Name
        useNormalizedAttrs: 'False'
    pagination_params_2:
      type: object
      description: Optional pagination parameters.
      properties:
        pageNum:
          type: integer
          description: Page number to retrieve (starting from page-1).
          example: 1
        pageSz:
          type: integer
          description: Number of records per page (max is 1000 per page).
          example: 500
    list_all_groups_in_domain_2:
      description: Retrieve all groups in a particular domain.
      allOf:
      - $ref: '#/components/schemas/domain_param'
      - $ref: '#/components/schema

# --- truncated at 32 KB (37 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/palo-alto-networks/refs/heads/main/openapi/palo-alto-networks-directory-sync-service-api-openapi.yml