openapi: 3.0.1
info:
  title: Connectivity AllowList Service
  description: Citrix Connectivity AllowList Service
  version: "v2"
servers:
  - url: https://api.cloud.com/connectivity
    description: For customers in US, AP-S, EU region
  - url: https://api.citrixcloud.jp/connectivity
    description: For customers in JP region

paths:
  /v2/allowlist:
    get:
      summary: Get the unified Citrix Cloud connectivity allowlist in canonical JSON or Zscaler format
      operationId: GetConnectivityAllowListV2
      tags:
        - AllowList Service V2
      parameters:
        - name: format
          in: query
          description: Optional response format. Defaults to `json`.
          schema:
            type: string
            enum:
              - json
              - zscaler
            default: json
        - name: customerId
          in: query
          required: false
          description: >-
            Conditionally required. Required when `format=json` (or format is omitted). Optional when `format=zscaler`.
          schema:
            type: string
            minLength: 1
            maxLength: 12
            pattern: '^[a-zA-Z0-9]{1,12}$'
          example: testcustomer
        - name: geo
          in: query
          description: Optional geographic filter. Defaults to `all`.
          schema:
            type: string
            enum:
              - us
              - eu
              - ap-s
              - jp
              - all
            default: all
        - name: direction
          in: query
          description: Optional traffic direction filter. Defaults to `all`.
          schema:
            type: string
            enum:
              - inbound
              - outbound
              - all
            default: all
        - name: Citrix-TransactionId
          in: header
          description: The Transaction Id.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: OK
          headers:
            citrix-transactionid:
              description: >-
                Globally-unique identifier (usually a GUID) that allows the flow
                of a call to be traced through all components within the system.
              schema:
                type: string
            content-type:
              description: Tells the type of the content in the response body.
              schema:
                type: string
                example: application/json
            cache-control:
              description: Holds directives for caching response.
              schema:
                type: string
                example: public, max-age=3600
            last-modified:
              description: Published allowlist version timestamp in IMF-fixdate format.
              schema:
                type: string
                example: Tue, 10 Mar 2026 00:00:00 GMT
            x-content-type-options:
              description: >-
                Marker used by the server to indicate that the MIME types
                advertised in the Content-Type headers should not be changed and
                be followed.
              schema:
                type: string
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/GetConnectivityAllowListV2Result'
                  - $ref: '#/components/schemas/GetConnectivityAllowListZscalerResult'
              examples:
                canonical:
                  summary: Canonical JSON response
                  value:
                    meta:
                      version: '2026-03-10T00:00:00Z'
                      validUntil: '2026-03-13T12:00:00Z'
                    services:
                      - name: DaaS
                        direction: outbound
                        endpoints:
                          - geo: us
                            fqdns:
                              - testcustomer.xendesktop.net
                            ips:
                              - 13.107.6.152/31
                        tcpPorts: 80,443
                        required: true
                        notes: Citrix Cloud control plane access
                zscaler:
                  summary: Zscaler Web Service Endpoint 1.3 compatible response
                  value:
                    usage:
                      update_interval: 84
                    services:
                      - id: daas-outbound-us-tcp-ipv4
                        name: DaaS outbound us tcp ipv4
                        type: non-real-time
                        protocol: tcp
                        ports: 80,443
                        domains:
                          - testcustomer.xendesktop.net
                        cidrs:
                          - 13.107.6.152/31
                    ipv6_services:
                      - id: daas-outbound-us-tcp-ipv6_service
                        name: DaaS outbound us tcp ipv6_service
                        type: non-real-time
                        protocol: tcp
                        ports: 80,443
                        cidrs:
                          - '2603:1006::/40'
        '400':
          $ref: '#/components/responses/BadRequestResponse'
        '404':
          $ref: '#/components/responses/NotFoundResponse'
        '429':
          $ref: '#/components/responses/TooManyRequestsResponse'

components:
  schemas:
    GetConnectivityAllowListV2Result:
      type: object
      properties:
        meta:
          $ref: '#/components/schemas/AllowListMetadata'
        services:
          type: array
          items:
            $ref: '#/components/schemas/AllowListService'
      required:
        - meta
        - services

    AllowListMetadata:
      type: object
      properties:
        version:
          type: string
          format: date-time
          example: '2026-03-10T00:00:00Z'
        validUntil:
          type: string
          format: date-time
          example: '2026-03-13T12:00:00Z'
      required:
        - version
        - validUntil

    AllowListService:
      type: object
      properties:
        name:
          type: string
          example: DaaS
        direction:
          type: string
          enum:
            - inbound
            - outbound
          example: outbound
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/AllowListEndpoint'
        tcpPorts:
          type: string
          description: TCP ports (comma-separated or ranges). At least one of tcpPorts or udpPorts must be present.
          example: 80,443
        udpPorts:
          type: string
          description: UDP ports (comma-separated or ranges). At least one of tcpPorts or udpPorts must be present.
          example: 123,500-600
        realtime:
          type: boolean
          description: Whether the service is latency-sensitive (real-time traffic).
          example: false
        required:
          type: boolean
          description: Indicates if the flow is required for product functionality. Should be present for all services.
          example: true
        notes:
          type: string
          description: Additional context about the service block. Should be present for all services.
          example: Citrix Cloud control plane access
      required:
        - name
        - direction
        - endpoints
      anyOf:
        - required:
            - tcpPorts
        - required:
            - udpPorts

    AllowListEndpoint:
      type: object
      properties:
        geo:
          type: string
          enum:
            - us
            - eu
            - ap-s
            - jp
            - all
          example: us
        fqdns:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
          example:
            - testcustomer.xendesktop.net
        ips:
          type: array
          minItems: 1
          items:
            type: string
            minLength: 1
          example:
            - 13.107.6.152/31
      required:
        - geo
      anyOf:
        - required:
            - fqdns
        - required:
            - ips

    GetConnectivityAllowListZscalerResult:
      type: object
      properties:
        usage:
          $ref: '#/components/schemas/ZscalerUsage'
        services:
          type: array
          items:
            $ref: '#/components/schemas/ZscalerService'
        ipv6_services:
          type: array
          items:
            $ref: '#/components/schemas/ZscalerService'
      required:
        - usage
        - services

    ZscalerUsage:
      type: object
      properties:
        update_interval:
          type: integer
          minimum: 1
          description: Hours until clients should refresh the published allowlist.
          example: 84
      required:
        - update_interval

    ZscalerService:
      type: object
      properties:
        id:
          type: string
          example: daas-outbound-us-tcp-ipv4
        name:
          type: string
          example: DaaS outbound us tcp ipv4
        type:
          type: string
          example: non-real-time
        protocol:
          type: string
          enum:
            - tcp
            - udp
          example: tcp
        ports:
          type: string
          example: 80,443
        domains:
          type: array
          items:
            type: string
          example:
            - testcustomer.xendesktop.net
        cidrs:
          type: array
          items:
            type: string
          example:
            - 13.107.6.152/31
      required:
        - id
        - name
        - type
        - protocol
        - ports

  responses:
    BadRequestResponse:
      description: Bad Request
      headers:
        citrix-transactionid:
          description: >-
            Globally-unique identifier (usually a GUID) that allows the flow
            of a call to be traced through all components within the system.
          schema:
            type: string
        content-type:
          description: Tells the type of the content in the request body.
          schema:
            type: string
        cache-control:
          description: Holds directives for caching response.
          schema:
            type: string
        x-content-type-options:
          description: >-
            Marker used by the server to indicate that the MIME types
            advertised in the Content-Type headers should not be changed and
            be followed.
          schema:
            type: string
    NotFoundResponse:
      description: Not Found
      headers:
        citrix-transactionid:
          description: >-
            Globally-unique identifier (usually a GUID) that allows the flow
            of a call to be traced through all components within the system.
          schema:
            type: string
        content-type:
          description: Tells the type of the content in the request body.
          schema:
            type: string
        cache-control:
          description: Holds directives for caching response.
          schema:
            type: string
        x-content-type-options:
          description: >-
            Marker used by the server to indicate that the MIME types
            advertised in the Content-Type headers should not be changed and
            be followed.
          schema:
            type: string
    TooManyRequestsResponse:
      description: Too Many Requests
      headers:
        citrix-transactionid:
          description: >-
            Globally-unique identifier (usually a GUID) that allows the flow
            of a call to be traced through all components within the system.
          schema:
            type: string
        content-type:
          description: Tells the type of the content in the request body.
          schema:
            type: string
        cache-control:
          description: Holds directives for caching response.
          schema:
            type: string
        retry-after:
          description: Suggested wait time before retrying after rate limiting.
          schema:
            type: integer
        x-content-type-options:
          description: >-
            Marker used by the server to indicate that the MIME types
            advertised in the Content-Type headers should not be changed and
            be followed.
          schema:
            type: string

tags:
  - name: AllowList Service V2
    description: Get the unified Citrix Cloud connectivity allowlist in canonical JSON or Zscaler format
