Skip to main content

Configuring AppProtection Profiles Using API

This article provides information on managing Zscaler Private Access (ZPA) AppProtection profile use cases using APIs. All APIs are rate limited. To learn more, see ZPA API Rate Limits.

Prerequisite API Calls

Before creating a new AppProtection profile, you must get the following required details:

Creating a New AppProtection Profile

To create a new AppProtection profile:

  1. Send a POST request to the following endpoint in the inspection-profile-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionProfile.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/72057594038056531/inspectionProfile.
  3. Include the request headers to provide information about the request context:
    • Content-Type: application/json
    • Authorization: Bearer <access_token>
  4. Use the following JSON payload and provide the following information:
    • Name of the application
    • Paranoia level: An integer which refers to the associated paranoia level. The supported values are 1, 2, 3, or 4.
  5. Ensure the required predefinedControls and predefinedControlsVersion fields are included in the JSON payload. All the mandatory predefined controls must be passed. To learn more, see Prerequisite API Calls.
NOTE

You choose the AppProtection profile criteria you want to include in the JSON payload. Refer to the Adding Field Descriptions section for supported values.

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

JSON Payload​

{
    "controlsInfo": [{
        "controlType": "CUSTOM",
        "count": 0
    }],
    "creationTime": 0,
    "customControls": [{
        "action": "PASS",
        "actionValue": "string",
        "associatedInspectionProfileNames": [{
            "id": 0,
            "name": "string"
        }],
        "controlNumber": 0,
        "controlRuleJson": "string",
        "creationTime": 0,
        "defaultAction": "PASS",
        "defaultActionValue": "string",
        "description": "string",
        "id": 0,
        "modifiedBy": 0,
        "modifiedTime": 0,
        "name": "string",
        "paranoiaLevel": 0,
        "rules": [{
            "conditions": [{
                "lhs": "SIZE",
                "op": "RX",
                "rhs": "string"
            }],
            "names": [
                "string"
            ],
            "type": "REQUEST_HEADERS"
        }],
        "severity": "CRITICAL",
        "type": "REQUEST",
        "version": "string"
    }],
    "description": "string",
    "globalControlActions": [
        "string"
    ],
    "id": 0,
    "incarnationNumber": 0,
    "modifiedBy": 0,
    "modifiedTime": 0,
    "name": "string",
    "paranoiaLevel": 0,
    "predefinedControls": [{
        "action": "PASS",
        "actionValue": "string",
        "associatedInspectionProfileNames": [{
            "id": 0,
            "name": "string"
        }],
        "attachment": "string",
        "controlGroup": "string",
        "controlNumber": 0,
        "creationTime": 0,
        "defaultAction": "PASS",
        "defaultActionValue": "string",
        "description": "string",
        "id": 0,
        "modifiedBy": 0,
        "modifiedTime": 0,
        "name": "string",
        "paranoiaLevel": 0,
        "severity": "CRITICAL",
        "version": "string"
    }],
    "predefinedControlsVersion": "string"
}

Minimum Criteria JSON Payload​

{
    "name": "string",
    "paranoiaLevel": "string",
    "predefinedControlsVersion": "string",
    "predefinedControls": [
      {
      "id": "string",
      "action": "string",
      "actionValue": "string"
      }
    ]
}

Example Response​

{
    "id": "73170362082263059",
    "modifiedTime": "1652719814",
    "creationTime": "1652719814",
    "modifiedBy": "72057594038056531",
    "name": "Example AppProtection Profile",
    "description": "desc",
    "paranoiaLevel": "1",
    "globalControlActions": [
       "PREDEFINED:NONE",
       "CUSTOM:NONE",
       "OVERRIDE_ACTION:NONE"
       ],
    "predefinedControlsVersion": "OWASP_CRS/3.3.0",
    "predefinedControls": [
       {
       "id": "72057594038049511",
       "action": "BLOCK"
       },
       {
       "id": "72057594038049512",
       "action": "BLOCK"
       },
       {
       "id": "72057594038049513",
       "action": "BLOCK"
       },
       {
       "id": "72057594038049514",
       "action": "BLOCK"
       },
       {
       "id": "72057594038050059",
       "action": "BLOCK"
       },
       {
       "id": "72057594038010025",
       "action": "BLOCK"
       },
       {
       "id": "72057594038010028",
       "action": "BLOCK"
       },
       {
       "id": "72057594038010032",
       "action": "BLOCK"
       },
       {
       "id": "72057594038010066",
       "action": "BLOCK"
      }
    ],
    "customControls": [
      {
      "id": "73170362082263045",
      "action": "PASS"
      }
    ],
    "incarnationNumber": "1",
    "commonGlobalOverrideActionsConfig": {
    "IS_OVERRIDE_ACTION_NONE": "TRUE"
    }
}

Adding Field Descriptions

The following table includes descriptions of available fields you may use for the AppProtection profile use cases:

FieldDescriptionRequiredValue
nameName of the applicationYesAny string
descriptionDescription of the applicationNoAny string
paranoiaLevelThe OWASP Predefined Paranoia Level. To learn more, see Configuring AppProtection Profiles.YesInteger
Range: [1-4], inclusive
associatedInspectionProfileNameName of the AppProtection profileNoString
controlNumberDomain name of the AppProtection applicationNoInteger
predefinedControlsVersionProtocol for the AppProtection applicationYesString
predefinedControlsThe predefined controlsYesJSON
predefinedControls.idID of the predefined controlYesString
predefinedControls.actionThe action of the predefined controlYesSupported values:
  • PASS
  • BLOCK
  • REDIRECT
predefinedControls.actionValueValue for the predefined controls action. This field is only required if the action is set to REDIRECT.YesString
InspectionPredefinedControl.attachmentControl attachmentNoString
InspectionPredefinedControl.controlGroupControl groupNoString
customControls.typeTypes for custom controlsNoString
customControls.controlRuleJsonCustom controls string in JSON formatNoString
customControls.rules.typeRequest headers for the custom controlsNoSupported values:
  • REQUEST_HEADERS
  • REQUEST_URI
  • QUERY_STRING
  • REQUEST_COOKIES
  • REQUEST_METHOD
  • REQUEST_BODY
  • RESPONSE_HEADER
  • RESPONSE_BODY
customControls.rules.namesName types for the custom controlsNoString
customControls.rules.conditions.lhsSignifies the key for the object typeNoString
customControls.rules.conditions.rhsDenotes the value for the given object type. Its value depends upon the key.NoString
customControls.rules.conditions.opDenotes the operation typeNoString
controlsInfo.controlTypeControl typesNoString. Supported values:
  • CUSTOM
  • PREDEFINED
  • ZSCALER
controlsInfo.countControl information countsNoLong

Getting Details for All AppProtection Profiles

To get all AppProtection profiles:

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

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

Example Response​

{
  "totalPages": "9",
  "list": [
    {
      "id": "217246660303025210",
      "modifiedTime": "1627001532",
      "creationTime": "1627001532",
      "modifiedBy": "72057594037994933",
      "name": "test_local",
      "description": "inspect simple http app ",
      "paranoiaLevel": "4",
      "globalControlActions": [
        "PREDEFINED:PASS",
        "CUSTOM:NONE",
        "OVERRIDE_ACTION:COMMON"
      ],
      "controlsInfo": [
        {
          "controlType": "PREDEFINED",
          "count": "50"
        }
      ],
      "incarnationNumber": "0",
      "commonGlobalOverrideActionsConfig": {
         "PREDEF_CNTRL_GLOBAL_ACTION": "PASS",
         "IS_OVERRIDE_ACTION_COMMON": "TRUE"
       }
    }
  ]   
}

Pagination​

This API supports pagination. To get a paginated response:

  1. Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/inspectionProfile?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/72057594037927936/inspectionProfile?page=1&pagesize=2.

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": "50",
  "list": [
    {
      "id": "72057594038049518",
      "modifiedTime": "1648567589",
      "creationTime": "1629746592",
      "modifiedBy": "72057594037973665",
      "name": "test",
      "description": "example description",
      "paranoiaLevel": "2",
      "globalControlActions": [
        "PREDEFINED:NONE",
        "CUSTOM:NONE",
        "OVERRIDE_ACTION:SPECIFIC"
      ],
      "controlsInfo": [
        {
          "controlType": "CUSTOM",
          "count": "1"
        },
        {
          "controlType": "PREDEFINED",
          "count": "207"
        }
      ],
      "incarnationNumber": "48",
      "commonGlobalOverrideActionsConfig": {
        "IS_OVERRIDE_ACTION_SPECIFIC": "TRUE"
      }
    },
    {
      "id": "72057594038071229",
      "modifiedTime": "1645227522",
      "creationTime": "1645227522",
      "modifiedBy": "72057594038006701",
      "name": "test2",
      "paranoiaLevel": "1",
      "globalControlActions": [
        "PREDEFINED:PASS",
        "CUSTOM:PASS",
        "OVERRIDE_ACTION:COMMON"
      ],
      "controlsInfo": [
        {
          "controlType": "CUSTOM",
          "count": "2"
        },
        {
          "controlType": "PREDEFINED",
          "count": "11"
        }
      ],
      "incarnationNumber": "1",
      "commonGlobalOverrideActionsConfig": {
        "PREDEF_CNTRL_GLOBAL_ACTION": "PASS",
        "CUSTOM_CNTRL_GLOBAL_ACTION": "PASS",
        "IS_OVERRIDE_ACTION_COMMON": "TRUE"
      }
    }
  ]
}

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/inspectionProfile&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 paranoiaLevel%20EQ%201 is supported for the Paranoia Level filter, using the Equals (EQ) operator, for the filter value 1.

    For example: /mgmtconfig/v1/admin/customers/73186051597795328/inspectionProfile&search=paranoiaLevel%20EQ%201.

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, paranoiaLevel%20EQ%201 is paranoiaLevel EQ 1.

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

Example Response​

{
  "totalPages": "71",
  "totalCount": "71",
  "list": [
    {
      "id": "72057594038071229",
      "modifiedTime": "1669379350",
      "creationTime": "1645227522",
      "modifiedBy": "72057594037940740",
      "name": "aaThreatlabzProfile",
      "description": "to test in-progress controls",
      "paranoiaLevel": "1",
      "globalControlActions": [
        "PREDEFINED:PASS",
        "CUSTOM:PASS",
        "WEBSOCKET:BLOCK",
        "THREATLABZ:NONE",
        "OVERRIDE_ACTION:COMMON"
      ],
      "controlsInfo": [
        {
          "controlType": "CUSTOM",
          "count": "2"
        },
        {
          "controlType": "PREDEFINED",
          "count": "60"
        },
        {
          "controlType": "WEBSOCKET_CUSTOM",
          "count": "1"
        },
        {
          "controlType": "WEBSOCKET_PREDEFINED",
          "count": "4"
        }
      ],
      "incarnationNumber": "53"
    }
  ]
}

Getting Details of the AppProtection Profile

To get details of the AppProtection profile:

  1. Send a GET request to the following endpoint in the inspection-profile-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionProfile/{inspectionProfileId}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • inspectionProfileId: The unique identifier of the inspection profile.

    For example: /mgmtconfig/v1/admin/customers/217246660302995456/inspectionProfile/217246660303025210.

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

Example Response​

{
  "id": "72057594038049518",
  "modifiedTime": "1648567589",
  "creationTime": "1629746592",
  "modifiedBy": "72057594037973665",
  "name": "sample name",
  "description": "sample description",
  "paranoiaLevel": "2",
  "globalControlActions": [
    "PREDEFINED:NONE",
    "CUSTOM:NONE",
    "OVERRIDE_ACTION:SPECIFIC"
  ],
  "predefinedControls": [
    {
      "id": "72057594038010284",
      "modifiedTime": "1619611688",
      "creationTime": "1619611688",
      "name": "SQL Injection Attack Data fetch attempt",
      "description": "This rule detects SQL Injection Attack by Data fetch attempt.",
      "severity": "CRITICAL",
      "controlNumber": "942480",
      "version": "OWASP_CRS/3.3.0",
      "paranoiaLevel": "2",
      "defaultAction": "BLOCK",
      "action": "BLOCK",
      "controlGroup": "SQL Injection"
    },
    {
      "id": "72057594038010287",
      "modifiedTime": "1619611688",
      "creationTime": "1619611688",
      "name": "SQLi bypass attempt by ticks or backticks detected",
      "description": "This rule detects SQL Injection bypass attempt by ticks or backticks.",
      "severity": "CRITICAL",
      "controlNumber": "942510",
      "version": "OWASP_CRS/3.3.0",
      "paranoiaLevel": "2",
      "defaultAction": "BLOCK",
      "action": "BLOCK",
      "controlGroup": "SQL Injection"
    },
    {
      "id": "72057594038010288",
      "modifiedTime": "1619611688",
      "creationTime": "1619611688",
      "name": "SQLi bypass attempt by ticks detected",
      "description": "This rule detects SQL Injection bypass attempt by ticks.",
      "severity": "CRITICAL",
      "controlNumber": "942511",
      "version": "OWASP_CRS/3.3.0",
      "paranoiaLevel": "3",
      "defaultAction": "BLOCK",
      "action": "BLOCK",
      "controlGroup": "SQL Injection"
    },
}

Updating an AppProtection Profile

To update an AppProtection profile:

  1. Send a PUT request to the following endpoint in the inspection-profile-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionProfile/{inspectionProfileId}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • inspectionProfileId: The unique identifier of the AppProtection profile.

    For example: /mgmtconfig/v1/admin/customers/217246660302995456/inspectionProfile/217246660303025210 in the inspection-profile-controller.

  3. Use the following JSON payload and provide the following information:

    • Name of the application
    • Paranoia level: An integer which refers to the associated paranoia level. The supported values are 1, 2, 3, or 4.
NOTE

Passing an empty list of custom or predefined controls in the JSON payload dissociates the controls from the AppProtection profile. The JSON payload passed for the PUT request to update the AppProtection profile is considered the source of truth and replaces the old custom or predefined controls with the new values. You choose the AppProtection profile criteria you want to include in the JSON payload. Refer to the Adding Field Descriptions section for supported values.

A successful response yields Code 204 - No Content, meaning the AppProtection profile is updated. To learn more, see ZPA API Codes.

JSON Payload​

{
    "controlsInfo": [{
        "controlType": "CUSTOM",
        "count": 0
    }],
    "creationTime": 0,
    "customControls": [{
        "action": "PASS",
        "actionValue": "string",
        "associatedInspectionProfileNames": [{
            "id": 0,
            "name": "string"
        }],
        "controlNumber": 0,
        "controlRuleJson": "string",
        "creationTime": 0,
        "defaultAction": "PASS",
        "defaultActionValue": "string",
        "description": "string",
        "id": 0,
        "modifiedBy": 0,
        "modifiedTime": 0,
        "name": "string",
        "paranoiaLevel": 0,
        "rules": [{
            "conditions": [{
                "lhs": "SIZE",
                "op": "RX",
                "rhs": "string"
            }],
            "names": [
                "string"
            ],
            "type": "REQUEST_HEADERS"
        }],
        "severity": "CRITICAL",
        "type": "REQUEST",
        "version": "string"
    }],
    "description": "string",
    "globalControlActions": [
        "string"
    ],
    "id": 0,
    "incarnationNumber": 0,
    "modifiedBy": 0,
    "modifiedTime": 0,
    "name": "string",
    "paranoiaLevel": 0,
    "predefinedControls": [{
        "action": "PASS",
        "actionValue": "string",
        "associatedInspectionProfileNames": [{
            "id": 0,
            "name": "string"
        }],
        "attachment": "string",
        "controlGroup": "string",
        "controlNumber": 0,
        "creationTime": 0,
        "defaultAction": "PASS",
        "defaultActionValue": "string",
        "description": "string",
        "id": 0,
        "modifiedBy": 0,
        "modifiedTime": 0,
        "name": "string",
        "paranoiaLevel": 0,
        "severity": "CRITICAL",
        "version": "string"
    }],
    "predefinedControlsVersion": "string"
}

Associating All Predefined Controls to an AppProtection Profile​

To associate all predefined controls with an AppProtection profile:

  1. Send a PUT request to the following endpoint in the inspection-profile-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionProfile/{inspectionProfileId}/associateAllPredefinedControls.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • inspectionProfileId: The unique identifier of the AppProtection profile.
    • version: The predefined control version. The supported value is OWASP_CRS/3.30.

    For example: /mgmtconfig/v1/admin/customers/217246660302995456/inspectionProfile/217246660303025210/associateAllPredefinedControls.

To associate all predefined controls to an AppProtection profile using a version:

  1. Send a PUT request to the following endpoint in the inspection-profile-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionProfile/{inspectionProfileId}/associateAllPredefinedControls?version=<version_id>.
  2. Provide the customerId, the ZPA tenant ID of the customer, in the request endpoint. For example: /mgmtconfig/v1/admin/customers/217246660302995456/inspectionProfile/217246660303025210/associateAllPredefinedControls?version=1.0.

A successful response yields Code 204 - No Content, meaning the AppProtection profile is updated. To learn more, see ZPA API Codes.

Dissociating All Predefined Controls from an AppProtection Profile​

To dissociate all predefined controls from an AppProtection profile:

  1. Send a PUT request to the following endpoint in the inspection-profile-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionProfile/{inspectionProfileId}/dissociateAllPredefinedControls.

    NOTE

    The previously supported API endpoint, /mgmtconfig/v1/admin/customers/{customerId}/inspectionProfile/{inspectionProfileId}/deAssociateAllPredefinedControls, is deprecated and is not supported from January 27, 2023.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • inspectionProfileId: The unique identifier of the AppProtection profile.

    For example: /mgmtconfig/v1/admin/customers/217246660302995456/inspectionProfile/217246660303025210/dissociateAllPredefinedControls

A successful response yields Code 204 - No Content, meaning the inspection profile is updated. To learn more, see ZPA API Codes.

Partially Updating the AppProtection Profile and Controls​

To partially update the AppProtection profile and controls:

  1. Send a PATCH request to the following endpoint in the inspection-profile-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionProfile/{inspectionProfileId}/patch.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • inspectionProfileId: The unique identifier of the AppProtection profile.

    For example: /mgmtconfig/v1/admin/customers/217246660302995456/inspectionProfile/217246660303025210/patch.

  3. Use the following JSON payload and provide the following information:

    • Name of the application
    • Paranoia level: An integer which refers to the associated paranoia level. The supported values are 1, 2, 3, or 4.
NOTE

The PATCH request to partially update the AppProtection profile and controls adds new controls or updates existing controls with the inputs in the payload. You choose the AppProtection profile criteria you want to include in the JSON payload. Refer to the Adding Field Descriptions section for supported values.

A successful response yields Code 204 - No Content, meaning the AppProtection profile is updated. To learn more, see ZPA API Codes.

JSON Payload​

{
    "controlsInfo": [{
        "controlType": "CUSTOM",
        "count": 0
    }],
    "creationTime": 0,
    "customControls": [{
        "action": "PASS",
        "actionValue": "string",
        "associatedInspectionProfileNames": [{
            "id": 0,
            "name": "string"
        }],
        "controlNumber": 0,
        "controlRuleJson": "string",
        "creationTime": 0,
        "defaultAction": "PASS",
        "defaultActionValue": "string",
        "description": "string",
        "id": 0,
        "modifiedBy": 0,
        "modifiedTime": 0,
        "name": "string",
        "paranoiaLevel": 0,
        "rules": [{
            "conditions": [{
                "lhs": "SIZE",
                "op": "RX",
                "rhs": "string"
            }],
            "names": [
                "string"
            ],
            "type": "REQUEST_HEADERS"
        }],
        "severity": "CRITICAL",
        "type": "REQUEST",
        "version": "string"
    }],
    "description": "string",
    "globalControlActions": [
        "string"
    ],
    "id": 0,
    "incarnationNumber": 0,
    "modifiedBy": 0,
    "modifiedTime": 0,
    "name": "string",
    "paranoiaLevel": 0,
    "predefinedControls": [{
        "action": "PASS",
        "actionValue": "string",
        "associatedInspectionProfileNames": [{
            "id": 0,
            "name": "string"
        }],
        "attachment": "string",
        "controlGroup": "string",
        "controlNumber": 0,
        "creationTime": 0,
        "defaultAction": "PASS",
        "defaultActionValue": "string",
        "description": "string",
        "id": 0,
        "modifiedBy": 0,
        "modifiedTime": 0,
        "name": "string",
        "paranoiaLevel": 0,
        "severity": "CRITICAL",
        "version": "string"
    }],
    "predefinedControlsVersion": "string"
}

Deleting an AppProtection Profile

To delete an AppProtection profile:

  1. Send a DELETE request to the following endpoint in the inspection-profile-controller: /mgmtconfig/v1/admin/customers/{customerId}/inspectionProfile/{inspectionProfileId}.

  2. Provide the following in the request endpoint:

    • customerId: The ZPA tenant ID of the customer.
    • inspectionProfileId: The unique identifier of the inspection profile.

    For example: /mgmtconfig/v1/admin/customers/217246660302995456/inspectionProfile/217246660303025210.

A successful response yields Code 204 - No Content, meaning the AppProtection profile is deleted. To learn more, see ZPA API Codes.