Palo Alto Networks Directory Sync Service API

openapi: 3.1.0
info:
  title: Palo Alto Networks AIOps for NGFW BPA 5G Deregistered Trend Directory Sync Service API
  description: AIOps for NGFW Best Practice Assessment (BPA) API. Provides programmatic access to submit BPA requests for Palo Alto Networks next-generation firewalls, check request processing status, and retrieve completed assessment reports. BPA reports analyze firewall configurations against Palo Alto Networks best practices and security benchmarks, identifying gaps and providing remediation guidance to improve security posture. Part of the Strata Cloud Manager platform.
  version: '1.0'
  contact:
    name: Palo Alto Networks Developer Support
    url: https://pan.dev/
  license:
    name: Proprietary
    url: https://www.paloaltonetworks.com/legal
servers:
- url: https://api.stratacloud.paloaltonetworks.com/aiops/bpa/v1
  description: AIOps for NGFW BPA API production server.
security:
- oauth2Bearer: []
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
components:
  schemas:
    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'
    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: &id001
              - 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: *id001
      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_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'
    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
    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_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'
    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
    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
    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
    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
    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: &id002
              - 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: *id002
      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
    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'
    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
  responses:
    500_internal_error:
      description: Internal service error
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              result:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      error-message:
                        type: string
                        example: Internal Server Error
    400_bad_request:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            type: object
            properties:
              statusCode:
                type: integer
                example: 400
              error:
                type: string
                example: Bad Request
              message:
                type: string
                example: Required field is missing or invalid.
  securitySchemes:
    oauth2Bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 Bearer token for SASE platform authentication. Obtain using the client_credentials grant with your SASE service account client ID and client secret.