Skip to main content

Managing App Connectors Using API

This article provides information about managing Zscaler Private Access (ZPA) App Connectors using APIs. All APIs are rate limited. To learn more, see ZPA API Rate Limits.

Getting Details for a Particular App Connector

To get details for a particular App Connector:

  1. Send a GET request to the following endpoint in the connector-controller: /mgmtconfig/v1/admin/customers/{customerId}/connector/{connectorId}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • connectorId: The App Connector ID of the customer.

    For example: /mgmtconfig/v1/admin/customers/217246660302995456/connector/217246660303024871.

A successful response returns code 200. To learn more, see ZPA API Codes.

Example Response​

{
  "id": "217246660303024871",
  "modifiedTime": "1617841545",
  "creationTime": "1617841545",
  "modifiedBy": "-2",
  "name": "example_provising_key-2",
  "fingerprint": "TQ0iesqrg2CwSD/CyyP/Tdb4XpEid0o/c8v9yTiJZVE=",
  "issuedCertId": "10723",
  "enabled": true,
  "upgradeAttempt": "0",
  "location": "British Columbia, Canada",
  "provisioningKeyId": "6211",
  "provisioningKeyName": "example_provising_key",
  "enrollmentCert": {
    "id": "2858",
    "name": "Mock Company Root Certificate"
  },
  "appConnectorGroupId": "217246660303024864",
  "appConnectorGroupName": "example_connector_group"
}

Getting Details for All App Connectors

To get details for all App Connectors:

  1. Send a GET request to the following endpoint in the connector-controller: /mgmtconfig/v1/admin/customers/{customerId}/connector.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/217246660302995456/connector.

A successful response returns code 200. To learn more, see ZPA API Codes.

Example Response​

 {
  "totalPages": "168",
  "list": [
    {
      "id": "217246660303024865",
      "modifiedTime": "1617747782",
      "creationTime": "1617747781",
      "modifiedBy": "-2",
      "name": "example_provising_key-1",
      "fingerprint": "ypAytG0R89+86b/HJEP3C86SJNiEjKLMXZGi7UzC070=",
      "issuedCertId": "10718",
      "enabled": true,
      "currentVersion": "21.67.2-5-gc17a10071-dirty",
      "upgradeStatus": "UNKNOWN",
      "controlChannelStatus": "ZPN_STATUS_DISCONNECTED",
      "upgradeAttempt": "0",
      "lastBrokerConnectTime": "1617750694",
      "lastBrokerConnectTimeDuration": "132d 19h 50m 43s",
      "lastBrokerDisconnectTime": "1617751234",
      "lastBrokerDisconnectTimeDuration": "132d 19h 41m 43s",
      "platform": "osx20",
      "latitude": "53.7266683",
      "longitude": "-127.647621",
      "location": "British Columbia, Canada",
      "provisioningKeyId": "6211",
      "provisioningKeyName": "example_provising_key",
      "enrollmentCert": {
        "id": "2858",
        "name": "Mock Company Root Certificate"
      },
      "appConnectorGroupId": "217246660303024864",
      "appConnectorGroupName": "example_connector_group"
    },
    {
      "id": "217246660303024871",
      "modifiedTime": "1617841545",
      "creationTime": "1617841545",
      "modifiedBy": "-2",
      "name": "example_provising_key-2",
      "fingerprint": "TQ0iesqrg2CwSD/CyyP/Tdb4XpEid0o/c8v9yTiJZVE=",
      "issuedCertId": "10723",
      "enabled": true,
      "upgradeAttempt": "0",
      "location": "British Columbia, Canada",
      "platformDetail": "ESXi",
      "provisioningKeyId": "6211",
      "provisioningKeyName": "example_provising_key",
      "enrollmentCert": {
        "id": "2858",
        "name": "Mock Company Root Certificate"
      },
      "appConnectorGroupId": "217246660303024864",
      "appConnectorGroupName": "example_connector_group"
    }
  ]
}

Supported Filters​

To search for App Connectors that last connected with the ZPA Public Service Edge for ZPA, use search=lastBrokerConnectTimeDuration LT (N), where (N) equals the days (d), hours (h), minutes (m), and seconds (s) in integers.

To search for all App Connectors that last disconnected with the ZPA Public Service Edge, use search=lastBrokerDisconnectTimeDuration LT (N), where (N) equals the days (d), hours (h), minutes (m), and seconds (s) in integers.

For example, to search for App Connectors that last connected with the ZPA Public Service Edge within 150 days, use search=lastBrokerConnectTimeDuration LT 150d.

The following filters are supported for use with the search parameter:

  • lastBrokerConnectTimeDuration: Filters for App Connectors that last connected with the ZPA Public Service Edge.
  • lastBrokerDisconnectTimeDuration: Filters for App Connectors that last disconnected with the ZPA Public Service Edge.
  • controlChannelStatus: Filters for inactive App Connectors.
  • currentVersion: Filters for the current version of the App Connector.
  • expectedVersion: Filters for the expected version of the App Connector based on the associated version profile.

For example, to search for an App Connector that has controlChannelStatus as disconnected with the last disconnected time greater than (N) days, use controlChannelStatus EQ ZPN_STATUS_DISCONNECTED AND lastBrokerDisconnectTimeDuration GT 15d.

The following rule tag operations are allowed:

  • GT: Greater than
  • LT: Less than
  • GTEQ: Greater than or equal to
  • LTEQ: Less than or equal to

Example Response​

{
  "totalPages": "128",
  "list": [
    {
      "id": "217246660303024865",
      "modifiedTime": "1617747782",
      "creationTime": "1617747781",
      "modifiedBy": "-2",
      "name": "example_provising_key-1",
      "fingerprint": "ypAytG0R89+86b/HJEP3C86SJNiEjKLMXZGi7UzC070=",
      "issuedCertId": "10718",
      "enabled": true,
      "currentVersion": "21.67.2-5-gc17a10071-dirty",
      "upgradeStatus": "UNKNOWN",
      "controlChannelStatus": "ZPN_STATUS_DISCONNECTED",
      "upgradeAttempt": "0",
      "lastBrokerConnectTime": "1617750694",
      "lastBrokerConnectTimeDuration": "181d 13h 38m 46s",
      "lastBrokerDisconnectTime": "1617751234",
      "lastBrokerDisconnectTimeDuration": "181d 13h 29m 46s",
      "platform": "osx20",
      "latitude": "53.7266683",
      "longitude": "-127.647621",
      "location": "British Columbia, Canada",
      "provisioningKeyId": "6211",
      "provisioningKeyName": "example_provising_key",
      "enrollmentCert": {
        "id": "2858",
        "name": "Mock Company Root Certificate"
      },
      "appConnectorGroupId": "217246660303024864",
      "appConnectorGroupName": "example_connector_group"
    },
    {
      "id": "217246660303025075",
      "modifiedTime": "1622502016",
      "creationTime": "1622502016",
      "modifiedBy": "-2",
      "name": "example_provising_key-4",
      "fingerprint": "TkL50KRJxbkaCEOLtkS/Exv9qeUoHcuMtTHfr/gS8FQ=",
      "issuedCertId": "10766",
      "enabled": true,
      "currentVersion": "21.172.1-703-g4f9451e18",
      "previousVersion": "21.172.1-703-g9cedf7b87-dirty",
      "lastUpgradeTime": "1628190895",
      "upgradeStatus": "UNKNOWN",
      "controlChannelStatus": "ZPN_STATUS_DISCONNECTED",
      "upgradeAttempt": "0",
      "lastBrokerConnectTime": "1628206943",
      "lastBrokerConnectTimeDuration": "60d 13h 07m 56s",
      "lastBrokerDisconnectTime": "1628209139",
      "lastBrokerDisconnectTimeDuration": "60d 12h 31m 21s",
      "platform": "osx20",
      "latitude": "53.7266683",
      "longitude": "-127.647621",
      "location": "British Columbia, Canada",
      "platformDetail": "ESXi",
      "provisioningKeyId": "6211",
      "provisioningKeyName": "example_provising_key",
      "enrollmentCert": {
        "id": "2858",
        "name": "Mock Company Root Certificate"
      },
      "appConnectorGroupId": "217246660303024864",
      "appConnectorGroupName": "example_connector_group"
    }
  ]
}
{
  "totalPages": "128",
  "list": [
    {
      "id": "217246660303024865",
      "modifiedTime": "1617747782",
      "creationTime": "1617747781",
      "modifiedBy": "-2",
      "name": "example_provising_key-1",
      "fingerprint": "ypAytG0R89+86b/HJEP3C86SJNiEjKLMXZGi7UzC070=",
      "issuedCertId": "10718",
      "enabled": true,
      "currentVersion": "21.67.2-5-gc17a10071-dirty",
      "upgradeStatus": "UNKNOWN",
      "controlChannelStatus": "ZPN_STATUS_DISCONNECTED",
      "upgradeAttempt": "0",
      "lastBrokerConnectTime": "1617750694",
      "lastBrokerConnectTimeDuration": "181d 13h 38m 46s",
      "lastBrokerDisconnectTime": "1617751234",
      "lastBrokerDisconnectTimeDuration": "181d 13h 29m 46s",
      "platform": "osx20",
      "latitude": "53.7266683",
      "longitude": "-127.647621",
      "location": "British Columbia, Canada",
      "provisioningKeyId": "6211",
      "provisioningKeyName": "example_provising_key",
      "enrollmentCert": {
        "id": "2858",
        "name": "Mock Company Root Certificate"
      },
      "appConnectorGroupId": "217246660303024864",
      "appConnectorGroupName": "example_connector_group"
    },
    {
      "id": "217246660303025075",
      "modifiedTime": "1622502016",
      "creationTime": "1622502016",
      "modifiedBy": "-2",
      "name": "example_provising_key-4",
      "fingerprint": "TkL50KRJxbkaCEOLtkS/Exv9qeUoHcuMtTHfr/gS8FQ=",
      "issuedCertId": "10766",
      "enabled": true,
      "currentVersion": "21.172.1-703-g4f9451e18",
      "previousVersion": "21.172.1-703-g9cedf7b87-dirty",
      "lastUpgradeTime": "1628190895",
      "upgradeStatus": "UNKNOWN",
      "controlChannelStatus": "ZPN_STATUS_DISCONNECTED",
      "upgradeAttempt": "0",
      "lastBrokerConnectTime": "1628206943",
      "lastBrokerConnectTimeDuration": "60d 13h 07m 56s",
      "lastBrokerDisconnectTime": "1628209139",
      "lastBrokerDisconnectTimeDuration": "60d 12h 31m 21s",
      "platform": "osx20",
      "latitude": "53.7266683",
      "longitude": "-127.647621",
      "location": "British Columbia, Canada",
      "provisioningKeyId": "6211",
      "provisioningKeyName": "example_provising_key",
      "enrollmentCert": {
        "id": "2858",
        "name": "Mock Company Root Certificate"
      },
      "appConnectorGroupId": "217246660303024864",
      "appConnectorGroupName": "example_connector_group"
    }
  ]
}

Pagination​

This API supports pagination. To get a paginated response:

  1. Send a GET request to the following endpoint in the connector-controller: /mgmtconfig/v1/admin/customers/{customerId}/connector?page=1&pagesize=20.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • Valid values for page and page size parameters.

    For example: /mgmtconfig/v1/admin/customers/217246660302995456/connector?page=1&pagesize=20.

NOTE

If not provided, the default page size is 20. The maximum page size is 500.

A successful response returns code 200. To learn more, see ZPA API Codes.

Example Response​

{
  "totalPages": "1",
  "list": [
    {
      "id": "144118148382064836",
      "modifiedTime": "1621702841",
      "creationTime": "1499716060",
      "modifiedBy": "-2",
      "name": "Azure Connector-1",
      "fingerprint": "Ic7rJNG6HQvjQ7EJj0uR76WBpm6mtCe3JCrLw91WmXE=",
      "issuedCertId": "258586",
      "enabled": true,
      "expectedVersion": "22.73.4",
      "currentVersion": "22.73.4",
      "previousVersion": "22.48.2",
      "lastUpgradeTime": "1647708745",
      "upgradeStatus": "COMPLETE",
      "controlChannelStatus": "ZPN_STATUS_AUTHENTICATED",
      "upgradeAttempt": "0",
      "ctrlBrokerName": "US-CA-9396",
      "lastBrokerConnectTime": "1649128946",
      "lastBrokerConnectTimeDuration": "17h 32m 50s",
      "sargeVersion": "17.20.2",
      "lastBrokerDisconnectTime": "1649128888",
      "lastBrokerDisconnectTimeDuration": "17h 33m 48s",
      "privateIp": "10.0.0.4",
      "publicIp": "10.0.0.1",
      "platform": "el7",
      "applicationStartTime": "1647708745",
      "latitude": "36.778261",
      "longitude": "-119.417932",
      "location": "California, USA",
      "platformDetail": "Azure",
      "provisioningKeyId": "554",
      "provisioningKeyName": "Azure Connector",
      "enrollmentCert": {
        "id": "117",
        "name": "Connector"
      },
      "appConnectorGroupId": "144118148382064835",
      "appConnectorGroupName": "Azure Connectors"
    },
    {
      "id": "144118148382065437",
      "modifiedTime": "1621702855",
      "creationTime": "1591139746",
      "modifiedBy": "-2",
      "name": "*Do not Delete* Lanukcorp AWS Connectors-4",
      "fingerprint": "Gvyg1hnlredGtyt7EWyLVRlyinXmXZnknbAfM9lClf4=",
      "issuedCertId": "258589",
      "enabled": true,
      "expectedVersion": "22.73.4",
      "currentVersion": "22.73.4",
      "previousVersion": "22.48.2",
      "lastUpgradeTime": "1647708563",
      "upgradeStatus": "COMPLETE",
      "controlChannelStatus": "ZPN_STATUS_AUTHENTICATED",
      "upgradeAttempt": "0",
      "ctrlBrokerName": "US-WA-0317",
      "lastBrokerConnectTime": "1649062642",
      "lastBrokerConnectTimeDuration": "01d 11h 57m 54s",
      "sargeVersion": "18.66.2",
      "lastBrokerDisconnectTime": "1647708499",
      "lastBrokerDisconnectTimeDuration": "17d 04h 06m 57s",
      "privateIp": "10.0.1.108",
      "publicIp": "52.222.36.1",
      "platform": "el7",
      "applicationStartTime": "1647711424",
      "latitude": "45.3573429",
      "longitude": "-122.606758",
      "location": "Oregon City, OR 97045, USA",
      "provisioningKeyId": "154",
      "provisioningKeyName": "*Do not Delete* Lanukcorp AWS Connectors",
      "enrollmentCert": {
        "id": "117",
        "name": "Connector"
      },
      "appConnectorGroupId": "144118148382064655",
      "appConnectorGroupName": "AWS Assistants"
    }
  ]
}

Search Option​

This API supports a search option to search by features and fields. To search by features and fields:

  1. Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/73186051597795328/connector&search={searchString}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • Valid search string values. The search string values are in the format fieldName operator fieldValue. Only search string values that correspond to the values for valid fields and filters are supported. For example, the string enabled%EQ%true is supported for the Status filter, using the Equals (EQ) operator, for the True (Enabled) filter value.

    For example: /mgmtconfig/v1/admin/customers/73186051597795328/connector&search=enabled%20EQ%20true.

NOTE

If you use the ZPA API Portal or the API Reference to make your API calls, the search field string does not require any characters. For example, enabled%20EQ%20true is enabled EQ true.

A successful response returns code 200. To learn more, see ZPA API Codes.

Example Response​

{
  "totalPages": "16",
  "totalCount": "16",
  "list": [
    {
      "id": "72057594038053055",
      "modifiedTime": "1662757554",
      "creationTime": "1633089623",
      "modifiedBy": "72057594038058534",
      "name": "Example App Connector",
      "description": "Example description",
      "fingerprint": "ZWM5OWM1ODcwMzcxMDJmOGY2Mzc3YjE5NjUyODJhOGUyZTAwNWMwZjhkN2",
      "enabled": true,
      "upgradeAttempt": "0",
      "location": "1234 Example Location",
      "microtenantName": "Default",
      "provisioningKeyId": "8588",
      "provisioningKeyName": "Abct",
      "appConnectorGroupId": "72057594038009372",
      "appConnectorGroupName": "Example App Connector Group"
    }
  ]
}

Updating an App Connector

To update an App Connector:

  1. Send a PUT request to the following endpoint in the connector-controller: /mgmtconfig/v1/admin/customers/{customerId}/connector/{connectorId}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • connectorId: The App Connector ID of the customer.

    For example: /mgmtconfig/v1/admin/customers/217246660302995456/connector/217246660303024871.

  3. Use the following JSON payload to update an App Connector and provide the following information about the App Connector:

    • name: Name of the App Connector.
    • description: Description of the App Connector.
    • enabled: Whether the App Connector is enabled or not.
NOTE

Refer to the Adding Field Descriptions section for supported values.

A successful response yields code 204, meaning the App Connector is updated. To learn more, see ZPA API Codes.

NOTE

If an App Connector is configured using Zscaler Deception, then the update and delete options are unavailable.

JSON Payload​

{
"description": "Test Connector",
"enabled": true,
"name": "Test_Connector",
}

Adding Field Descriptions

The following table includes descriptions of available fields you can use for the App Connector use cases:

FieldDescriptionRequiredValue
nameName of the App ConnectorNoString
descriptionDescription of the App ConnectorNoString
enabledWhether the App Connector is enabled or notNoDefault: true
Supported values: true, false
microtenantIdThe unique identifier of the Microtenant for the ZPA tenant. If you are within a Microtenant, you must pass the microtenantId field when making an API call to retrieve data from that Microtenant. The microtenantId can be obtained in the API Keys page, or can be obtained programmatically using the ZPA cloud service API. Access to certain operations are limited when you are within a Microtenant. If you are within the Default Microtenant, pass microtenantId as 0 when making requests to retrieve data from the Default Microtenant. Pass microtenantId as null to retrieve data from all Microtenants associated with the tenant. If the microtenantId is not passed in the request when creating or updating a resource, then the resource is created or updated in the Default Microtenant. To learn more, see Configuring Microtenants Using API.NoInteger

Deleting an App Connector

To delete an App Connector:

  1. Send a DELETE request to the following endpoint in the connector-controller: /mgmtconfig/v1/admin/customers/{customerId}/connector/{connectorId}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • connectorId: The App Connector ID of the customer.

    For example: /mgmtconfig/v1/admin/customers/217246660302995456/connector/217246660303024871.

A successful response yields code 204, meaning the App Connector is deleted. To learn more, see ZPA API Codes.

NOTE

If an App Connector is configured using Zscaler Deception, then the update and delete options are unavailable.

Bulk Deleting App Connectors

To bulk delete App Connectors:

  1. Provide the following JSON payload with the App Connector IDs you wish to bulk delete, then send a POST request to the following endpoint in the connector-controller: /mgmtconfig/v1/admin/customers/{customerId}/connector/bulkDelete.

    JSON Payload:

    {
    "ids": [
    "<AppConnectorId>",
    "<AppConnectorId2>"
    ]
    }

    Example JSON Payload:

    {
    "ids": [
    "217246660303024723",
    "217246660303024725"
    ]
    }

  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/217246660302995456/connector/bulkDelete.

A successful response yields code 200, meaning the App Connectors are deleted. To learn more, see ZPA API Codes.