Configuring Access Policies Using API

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

Prerequisite API Call

To get the policySetId by policy type:

1. Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/policySet/policyType/{policyType}.

2. Provide the policyType, the value for differentiating the policy types, in the request endpoint. The supported values are:

   • ACCESS_POLICY or GLOBAL_POLICY (i.e., access policy)
   • TIMEOUT_POLICY or REAUTH_POLICY (i.e., timeout policy)
   • BYPASS_POLICY or CLIENT_FORWARDING_POLICY (i.e., client forwarding policy)
   • INSPECTION_POLICY (i.e., AppProtection policy)
   • ISOLATION_POLICY (i.e., Isolation policy)
   • REDIRECTION_POLICY (i.e., redirection policy)
   • CAPABILITIES_POLICY (i.e., privileged capabilities policy)
   • CREDENTIAL_POLICY (i.e., privileged credential policy)
   • CLIENTLESS_SESSION_PROTECTION_POLICY (i.e., Browser Protection policy)
   • PRIVILEGED_PORTAL_POLICY (i.e., privileged portal policy)

   For example: /mgmtconfig/v1/admin/customers/217246660302995456/policySet/policyType/ACCESS_POLICY.

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

Example Response

{
  "id":"217246660303020009",
  "modifiedTime":"1627689868",
  "creationTime":"1480979629",
  "modifiedBy":"217246660303025242",
  "name":"Global_Policy",
  "enabled":true,
  "description":"The rules in this policy set are executed first.",
  "policyType":"1"
}

Pagination

This API supports pagination. To get a paginated response:

1. Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/policySet/rules/policyType/{policyType}?page=1&pagesize=20.

2. Provide the following in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • policyType: The value for differentiating the policy types. The supported values are:
     • ACCESS_POLICY or GLOBAL_POLICY (i.e., access policy)
     • TIMEOUT_POLICY or REAUTH_POLICY (i.e., timeout policy)
     • BYPASS_POLICY or CLIENT_FORWARDING_POLICY (i.e., client forwarding policy)
     • INSPECTION_POLICY (i.e., AppProtection policy)
     • ISOLATION_POLICY (i.e., Isolation policy)
     • REDIRECTION_POLICY (i.e., redirection policy)
     • CAPABILITIES_POLICY (i.e., privileged capabilities policy)
     • CREDENTIAL_POLICY (i.e., privileged credential policy)
     • CLIENTLESS_SESSION_PROTECTION_POLICY (i.e., Browser Protection policy)
     • PRIVILEGED_PORTAL_POLICY (i.e., privileged portal policy)
   • Valid values for page and page size parameters.

   For example: /mgmtconfig/v1/admin/customers/217246660302995456/policySet/rules/policyType/ACCESS_POLICY?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":"16",
  "list":[
     {
        "id":"217246660303025578",
        "modifiedTime":"1643242692",
        "modifiedBy":"217246660303024774",
        "name":"Test all access",
        "ruleOrder":"1",
        "priority":"31",
        "policyType":"1",
        "operator":"AND",
        "conditions":[
           {
              "id":"635818",
              "modifiedTime":"1643242692",
              "creationTime":"1643242692",
              "modifiedBy":"217246660303024774",
              "operator":"OR",
              "negated":false,
              "operands":[
                 {
                    "id":"635819",
                    "creationTime":"1643242692",
                    "modifiedBy":"217246660303024774",
                    "objectType":"APP",
                    "lhs":"id",
                    "rhs":"217246660303025577",
                    "name":"TEST-MOCK"
                 },
                 {
                    "id":"635820",
                    "creationTime":"1643242692",
                    "modifiedBy":"217246660303024774",
                    "objectType":"APP",
                    "lhs":"id",
                    "rhs":"217246660303025612",
                    "name":"TEST-COPY"
                 },
                 {
                    "id":"635821",
                    "creationTime":"1643242692",
                    "modifiedBy":"217246660303024774",
                    "objectType":"APP",
                    "lhs":"id",
                    "rhs":"217246660303025613",
                    "name":"TEST-MOCK2"
                 },
                 {
                    "id":"635822",
                    "creationTime":"1643242692",
                    "modifiedBy":"217246660303024774",
                    "objectType":"APP_GROUP",
                    "lhs":"id",
                    "rhs":"217246660303025575",
                    "name":"TEST-MOCK"
                 },
                 {
                    "id":"635823",
                    "creationTime":"1643242692",
                    "modifiedBy":"217246660303024774",
                    "objectType":"APP_GROUP",
                    "lhs":"id",
                    "rhs":"217246660303025610",
                    "name":"TEST-COPY"
                 },
                 {
                    "id":"635824",
                    "creationTime":"1643242692",
                    "modifiedBy":"217246660303024774",
                    "objectType":"TEST APP_GROUP",
                    "lhs":"id",
                    "rhs":"217246660303025615",
                    "name":"TEST_COPY2"
                 }
              ]
           }
        ],
        "action":"ALLOW",
        "customMsg":"TEST access rule",
        "defaultRule":false
     },
     {
        "id":"217246660303023504",
        "modifiedTime":"1642482351",
        "modifiedBy":"72057594037995189",
        "name":"All_Test",
        "ruleOrder":"2",
        "priority":"31",
        "policyType":"1",
        "operator":"AND",
        "action":"ALLOW",
        "customMsg":"Have fun",
        "defaultRule":false
     }
  ]
}

Search Option

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

1. Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/policySet/rules/policyType/{policyType}?page=1&pagesize=20&search={searchString}.

2. Provide the following in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • policyType: The value for differentiating the policy types. The supported values are:
     • ACCESS_POLICY or GLOBAL_POLICY (i.e., access policy)
     • TIMEOUT_POLICY or REAUTH_POLICY (i.e., timeout policy)
     • BYPASS_POLICY or CLIENT_FORWARDING_POLICY (i.e., client forwarding policy)
     • INSPECTION_POLICY (i.e., AppProtection policy)
     • ISOLATION_POLICY (i.e., Isolation policy)
     • REDIRECTION_POLICY (i.e., redirection policy)
     • CAPABILITIES_POLICY (i.e., privileged capabilities policy)
     • CREDENTIAL_POLICY (i.e., privileged credential policy)
     • CLIENTLESS_SESSION_PROTECTION_POLICY (i.e., Browser Protection policy)
     • PRIVILEGED_PORTAL_POLICY (i.e., privileged portal policy)
   • Valid page and page size values.
   • Valid search string values. The search string values are in the format action OPERATOR ruleAction. The supported ruleAction values for access policies are ALLOW and DENY. The supported value for OPERATOR is EQ (i.e., equals). Only search string values that correspond to the values for valid rule actions and operators are supported. For example, the string action%20EQ%ALLOW is supported for the Rule Action filter, using the Equals operator, for the ALLOW rule action.

   For example: /mgmtconfig/v1/admin/customers/72057594037927936/policySet/rules/policyType/ACCESS_POLICY?page=1&pagesize=500&search=action%20EQ%20ALLOW.

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",
   "totalCount":"0",
   "list":[
      {
         "id":"72057594037928147",
         "modifiedTime":"1690194270",
         "modifiedBy":"72057594037941138",
         "name":"yob",
         "ruleOrder":"1",
         "priority":"1",
         "policyType":"1",
         "operator":"AND",
         "action":"ALLOW",
         "defaultRule":false,
         "restrictedEntity":false
      },
      {
         "id":"72057594038004605",
         "modifiedTime":"1675769235",
         "modifiedBy":"72057594037959293",
         "name":"test232",
         "ruleOrder":"3",
         "priority":"1",
         "policyType":"1",
         "operator":"AND",
         "action":"ALLOW",
         "defaultRule":false,
         "restrictedEntity":false
      },
      {
         "id":"72057594038007682",
         "creationTime":"1676967351",
         "modifiedBy":"72057594037993505",
         "name":"adfasf",
         "description":"asfas",
         "ruleOrder":"4",
         "priority":"1",
         "policyType":"1",
         "operator":"AND",
         "action":"ALLOW",
         "defaultRule":false,
         "restrictedEntity":false
      }
   ]
}

Getting the Required Policy Criteria Details

Before creating a new access policy rule, you must get the following required details for the policy criteria:

• Application Segment. To learn more, see Configuring Application Segments Using API.
• Client types. To learn more, see Getting Details of All Client Types.
• Cloud Connector Group. To learn more, see Obtaining Cloud Connector Group Details Using API.
• IdP. To learn more, see Obtaining IdP Configuration Details Using API.
• Machine Group. To learn more, see Obtaining Machine Group Details Using API.
• Platform types. To learn more, see Getting Platform Types for a Customer.
• Posture profile. To learn more, see Obtaining Posture Profile Details Using API.
• SAML attribute. To learn more, see Obtaining SAML Attribute Details Using API.
• Segment Group. To learn more, see Configuring Segment Groups Using API.
• SCIM attribute. To learn more, see Obtaining SCIM Attribute Details Using API.
• SCIM attribute value. To learn more, see Obtaining SCIM Attribute Details Using API.
• SCIM Group. To learn more, see Obtaining SCIM Group Details Using API.
• Trusted network. To learn more, see Obtaining Trusted Network Details Using API.

Creating a New Access Policy Rule

To add a new access policy rule for a given policy set and for a given customerId:

1. Send a POST request to the following endpoint: /mgmtconfig/v2/admin/customers/{customerId}/policySet/{policySetId}/rule.

2. Provide the following in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • policySetId: The ID of the global policy set captured in Prerequisite API Call.

   For example: /mgmtconfig/v2/admin/customers/217316918451765248/policySet/217316918451765253/rule.

3. Include the request headers to specify the following parameters about the request context:

   • Content-Type: application/json
   • Authorization: Bearer <access_token>

4. Use the entire JSON payload and provide the policy criteria you want for the criteria.

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

JSON Payload

{
    "policySetId": "<policySetId>",
    "conditions": [
        {
            "operands": [
                {
                    "objectType": "APP",
                    "values": [
                        "<applicationId>",
                        "<applicationId>",
                        "<applicationId>"
                    ]
                },
                {
                    "objectType": "APP_GROUP",
                    "values": [
                        "<segmentGroupId>"
                    ]
                }
            ]
        }
    ],
    "name": "<Example Policy Rule Name>",
    "description": "<Example Policy Rule Description>",
    "action": "ALLOW",
    "appConnectorGroups": [
        {
            "id": "<appConnectorGroupId>",
            "name": "<Example App Connector Group Name>"
        },
        {
            "id": "<appConnectorGroupId>",
            "name": "<Example App Connector Group Name 2>"
        }
    ],
    "appServerGroups": [],
    "customMsg": "MsgString"
}

Example Response

{
  "id":"72057615512764594",
  "creationTime":"1612289724",
  "modifiedBy":"72057615512764593",
  "name":"PolicyName",
  "description":"Description",
  "ruleOrder":"5",
  "priority":"1",
  "policyType":"1",
  "operator":"AND",
  "action":"ALLOW",
  "customMsg":"MsgString",
  "auditMessage":"string"
}

Privileged Remote Access Support

To create an access policy rule with a required approval:

1. Send a POST request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/policySet/{policySetId}/rule?microtenantId={microtenantId}.

2. Provide the following in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • policySetId: The ID of the global policy set captured in the Prerequisite API Call section.
   • microtenantId: The unique identifier of the Microtenant for the ZPA tenant. To learn more, see Configuring Microtenants Using API.

   For example: /mgmtconfig/v1/admin/customers/289370814522851328/policySet/289370814522851333/rule?microtenantId=145260601092866314.

3. Include the request headers to specify the following parameters about the request context:

   • Content-Type: application/json
   • Authorization: Bearer <access_token>

4. Use the following JSON payload and provide the following:

   • Ensure action is set to REQUIRE_APPROVAL
   • The policy criteria you want to include.

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

JSON Payload

{
   "action":"REQUIRE_APPROVAL",
   "actionId":0,
   "appServerGroups":[
      {
         "configSpace":"DEFAULT",
         "creationTime":0,
         "description":"string",
         "enabled":true,
         "id":0,
         "learningEnabled":true,
         "modifiedBy":0,
         "modifiedTime":0,
         "name":"string",
         "restrictedEntity":true
      }
   ],
   "connectorGroups":[
      {
         "connectors":[
            {
               "applicationStartTime":0,
               "connectorGroupId":"string",
               "connectorGroupName":"string",
               "controlChannelStatus":"UNKNOWN",
               "creationTime":0,
               "ctrlBrokerName":"string",
               "currentVersion":"string",
               "description":"string",
               "enabled":true,
               "expectedUpgradeTime":0,
               "expectedVersion":"string",
               "fingerprint":"string",
               "id":0,
               "ipAcl":[
                  "string"
               ],
               "issuedCertId":0,
               "lastBrokerConnectTime":0,
               "lastBrokerConnectTimeDuration":"string",
               "lastBrokerDisconnectTime":0,
               "lastBrokerDisconnectTimeDuration":"string",
               "lastUpgradeTime":0,
               "latitude":0,
               "location":"string",
               "longitude":0,
               "modifiedBy":0,
               "modifiedTime":0,
               "name":"string",
               "nonceId":0,
               "nonceName":"string",
               "platform":"string",
               "platformDetail":"string",
               "previousVersion":"string",
               "privateIp":"string",
               "publicIp":"string",
               "restrictedEntity":true,
               "sargeVersion":"string",
               "signingCert":{
                  "additionalProp1":"string",
                  "additionalProp2":"string",
                  "additionalProp3":"string"
               },
               "upgradeAttempt":0,
               "upgradeStatus":"COMPLETE"
            }
         ],
         "cityCountry":"string",
         "countryCode":"string",
         "creationTime":0,
         "description":"string",
         "dnsQueryType":"IPV4_IPV6",
         "enabled":true,
         "geoLocationId":0,
         "id":0,
         "ipAcl":[
            "string"
         ],
         "latitude":"string",
         "location":"string",
         "longitude":"string",
         "modifiedBy":0,
         "modifiedTime":0,
         "name":"string",
         "overrideVersionProfile":true,
         "restrictedEntity":true,
         "serverGroups":[
            {
               "configSpace":"DEFAULT",
               "creationTime":0,
               "description":"string",
               "enabled":true,
               "id":0,
               "learningEnabled":true,
               "modifiedBy":0,
               "modifiedTime":0,
               "name":"string",
               "restrictedEntity":true
            }
         ],
         "lssAppConnectorGroup":true,
         "tcpQuickAckApp":true,
         "tcpQuickAckAssistant":true,
         "tcpQuickAckReadAssistant":true,
         "upgradeDay":"string",
         "upgradeTimeInSecs":"string",
         "versionProfileId":0,
         "versionProfileName":"string",
         "versionProfileVisibilityScope":"ALL"
      }
   ],
   "conditions":[
      {
         "creationTime":0,
         "id":0,
         "modifiedBy":0,
         "modifiedTime":0,
         "negated":true,
         "operands":[
            {
               "creationTime":0,
               "id":0,
               "idpId":0,
               "lhs":"string",
               "modifiedBy":0,
               "modifiedTime":0,
               "name":"string",
               "objectType":"USER",
               "rhs":"string"
            }
         ],
         "operator":"AND"
      }
   ],
   "creationTime":0,
   "customMsg":"string",
   "defaultRule":true,
   "defaultRuleName":"string",
   "description":"string",
   "id":0,
   "modifiedBy":0,
   "modifiedTime":0,
   "name":"string",
   "operator":"AND",
   "policySetId":0,
   "policyType":0,
   "priority":0,
   "reauthIdleTimeout":0,
   "reauthTimeout":0,
   "restrictedEntity":true,
   "ruleOrder":0,
   "zpnCbiProfileId":0,
   "zpnInspectionProfileId":0,
   "zpnInspectionProfileName":"string"
}

Example JSON Payload

{
   "policySetId":"289370814522851333",
   "conditions":[
      
   ],
   "name":"krishna-test1",
   "description":"krishna-test1",
   "action":"REQUIRE_APPROVAL",
   "connectorGroups":[
      
   ],
   "appServerGroups":[
      
   ],
   "customMsg":"krishna-test1"
}

Example Response

{
   "id":"289370814522851657",
   "creationTime":"1669729158",
   "modifiedBy":"72057594038624153",
   "name":"krishna-test1",
   "description":"krishna-test1",
   "microtenantId":145260601092866314,
   "ruleOrder":"12",
   "priority":"1",
   "policyType":"1",
   "operator":"AND",
   "action":"REQUIRE_APPROVAL",
   "customMsg":"krishna-test1",
   "policySetId":"289370814522851333",
   "privilegedCapabilities":{
      
   },
   "defaultRule":false
}

Adding Field Descriptions

The following table includes descriptions of available fields you can use for the access policy use cases:

Field	Description	Required	Value
name	This is the name of the access policy rule	Yes	String
description	This is the description of the access policy rule	No	String
action	This is for providing the rule action	Yes	Supported values: ALLOW (default value) DENY REQUIRE_APPROVAL
customerMsg	This is for providing a customer message for the user	No	String
conditions	This is for providing the set of conditions for the policy	No	Array of operands
appConnectorGroups	The IDs and names of the App Connector groups for the application that you want the access policy to use. If no App Connector groups are specified in the payload, then all App Connector groups for the application are selected. The maximum limit of selected App Connector groups is 48. If all App Connector groups for the application are selected, then only 48 App Connector groups are used. This limit applies to newly created or edited policy rules after March 4, 2024.	No
operands	This signifies the various policy criteria	No	Array of attributes (objectType, lhs, rhs, name)
objectType	This is for specifying the policy criteria	No	Supported values: AAE_PROFILE: Denotes the Adaptive Access Profiles policy criteria. - APP: Denotes the Applications policy criteria. APP_GROUP: Denotes the segments groups for the Applications policy criteria. BRANCH_CONNECTOR_GROUP: Denotes the Branch Connector Groups policy criteria. CHROME_ENTERPRISE: Denotes the Chrome Enterprise Browser policy criteria. CHROME_POSTURE_PROFILE: Denotes the Chrome posture profiles for the Chrome Enterprise Browser policy criteria. CLIENT_TYPE: Denotes the Client Types policy criteria. CONSOLE: Denotes the console ID for the Chrome Enterprise Browser policy criteria. COUNTRY_CODE: Denotes the Country Code policy criteria. EDGE_CONNECTOR_GROUP: Denotes the Cloud Connector Groups policy criteria. EXTRANET_LOCATION: Denotes the extranet locations for the Extranet Location policy criteria. EXTRANET_LOCATION_GROUP: Denotes the extranet location groups for the Extranet Location policy criteria. IAM_IDP_ID: Denotes the Authentication Service IdP for the SAML and SCIM Attributes policy critera. IDP: Denotes the IdP for the SAML and SCIM Attributes policy criteria. LOCATION: Denotes the Locations policy criteria. MACHINE_GRP: Denotes the Machine Groups policy criteria. PLATFORM: Denotes the Platforms policy criteria. POSTURE: Denotes the Client Connector Posture Profiles policy criteria. PRIVILEGE_PORTAL: Denotes the Privileged Portals policy criteria. RISK_FACTOR_TYPE: Denotes the Risk Scores policy criteria. SAML: Denotes the SAML attributes for the SAML and SCIM Attributes policy criteria. SCIM: Denotes the SCIM attributes for the SAML and SCIM Attributes policy criteria. SCIM_GROUP: Denotes the SCIM groups for the SAML and SCIM Attributes policy criteria. TRUSTED_NETWORK: Denotes the Client Connector Trusted Networks policy criteria. WORKLOAD_TAG_GROUP: Denotes the Workload Groups policy criteria. To learn more, see LHS and RHS Values. POSTURE and TRUSTED_NETWORK values are only supported for the CLIENT_TYPE.
lhs	This signifies the key for the object type	No	String ID example: "id"
rhs	This denotes the value for the given object type. Its value depends upon the key.	No	For APP, APP_GROUP, and IDP, the supported value is entity id. For CLIENT_TYPE, the supported values are zpn_client_type_zapp (for Zscaler Client Connector) and zpn_client_type_exporter (for Clientless). For POSTURE, the supported values are: true (verified), false (verification failed). For TRUSTED_NETWORK, the supported value is true.
operator	This denotes the operation type	No	Supported values: AND, OR.
microtenantId	The 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. 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.	No	Integer

LHS and RHS Values

LHS and RHS values differ based on object types. If the objectType value within the operands model is set to any of the following, then you must include attributes in the values model (i.e., an array of strings) inside each of the operands:

• AAE_PROFILE: Denotes the Adaptive Access Profiles policy criteria. The supported attribute is an array of adaptive access profile IDs.
• APP: Denotes the Applications policy criteria. The supported attribute is an array of application IDs.
• APP_GROUP: Denotes the segments groups for the Applications policy criteria. The supported attribute is an array of segment group IDs.
• BRANCH_CONNECTOR_GROUP: Denotes the Branch Connector Groups policy criteria. The supported attribute is an array of Branch Connector group IDs.
• CLIENT_TYPE: Denotes the Client Types policy criteria. The supported attribute is an array of client types. The following attributes are supported for CLIENT_TYPE:
  • 0: "zpn_client_type_branch_connector": Denotes the Branch Connector client type.
  • 1: "zpn_client_type_zapp_partner": Denotes the Client Connector Partner client type.
  • 2: "zpn_client_type_ip_anchoring": Denotes the ZIA Service Edge client type.
  • 3: "zpn_client_type_zapp": Denotes the Client Connector client type.
  • 4: "zpn_client_type_eas_client": Denotes the Extranet client type.
  • 5: "zpn_client_type_vdi": Denotes the Client Connector for VDI client type.
  • 6: "zpn_client_type_edge_connector": Denotes the Cloud Connector client type.
  • 7: "zpn_client_type_machine_tunnel": Denotes the Machine Tunnel client type.
  • 8: "zpn_client_type_exporter": Denotes the Web Browser client type.
• CHROME_POSTURE_PROFILE: Denotes the Chrome posture profiles for the Chrome Enterprise Profile policy criteria. The supported attribute is an array of Chrome posture profile IDs.
• CONSOLE: Denotes the console ID for the Chrome Enterprise Browser policy criteria. The supported attribute is an array of console IDs.
• EDGE_CONNECTOR_GROUP: Denotes the Cloud Connector groups for the Cloud Connector Group policy criteria. The supported attribute is an array of Cloud Connector group IDs.
• IAM_IDP_ID: Denotes the Authentication Service IdP for the SAML and SCIM Attributes policy critera. The supported attribute is an array of IdP IDs.
• IDP : Denotes the IdPs for the SAML and SCIM Attributes policy criteria. The supported attribute is an array of IdP IDs.
• LOCATION: Denotes the Locations policy criteria. The supported attribute is an array of location IDs.
• MACHINE_GRP: Denotes the Machine Groups policy criteria. The supported attribute is an array of machine group IDs.
• PRIVILEGE_PORTAL: Denotes the Privileged Portals policy criteria. The supported attribute is an array of privileged portal IDs.
• WORKLOAD_TAG_GROUP: Denotes the Workload Groups policy criteria. The supported attribute is an array of workload group IDs.

Example Payload:

"conditions": [
       {
           "operands": [
               {
                   "objectType": "APP",
                   "values": [
                       "72057594038619453"
                   ]
               },
               {
                   "objectType": "APP_GROUP",
                   "values": [
                       "72057594038619463"
                   ]
               }
           ]
       },

If the objectType value within the operands model is set to the following, then the entryValues property must be added to include the related lhs and rhs values:

• EXTRANET_LOCATION: Denotes the extranet locations for the Extranet Location policy criteria.
• EXTRANET_LOCATION_GROUP: Denotes the extranet location groups for the Extranet Location policy criteria.
• PLATFORM: Denotes the Platforms policy criteria.
• POSTURE: Denotes the Client Connector Posture Profiles policy criteria.
• RISK_FACTOR_TYPE: Denotes the Risk Scores policy criteria.
• SAML: Denotes the SAML attributes for the SAML and SCIM Attributes policy criteria.
• SCIM: Denotes the SCIM attributes for the SAML and SCIM Attributes policy criteria.
• SCIM_GROUP: Denotes the SCIM groups for the SAML and SCIM Attributes policy
  NOTE

  If you are subscribed to Authentication Service for users, SCIM and SCIM_GROUP are replaced by USER and USER_GROUP values.

• TRUSTED_NETWORK: Denotes the Client Connector Trusted Networks policy criteria.

Example Payload:

"conditions": [
        {
            "operands": [
                {
                    "objectType": "SAML",
                    "entryValues": [
                        {
                            "lhs": "72057594038637267",
                            "rhs": "A"
                        }
                    ]
                }
            ],
            "operator": "OR"
        }
    ],

Refer to the following table for the supported LHS and RHS values per object type:

Object Type	LHS	RHS
AAE_PROFILE	"<ID>"	"<profile ID>"
APP	"<ID>"	"<application segment ID>" (e.g., "144118148382065459")
APP_GROUP	"<ID>"	"<app segment group ID>" (e.g., "144118148382065533")
BRANCH_CONNECTOR_GROUP	"<ID>"	"Branch Connector group ID>" (e.g., "73203803771372526")
CHROME_ENTERPRISE	"managed"	"true"
CHROME_POSTURE_PROFILE	"<ID>"	"<posture profile ID>" (e.g., "72057594038857098")
CONSOLE	"<ID>"	"<console ID>" (e.g., "73237706095733389")
CLIENT_TYPE	"<ID>"	The following values are supported: - 0: "zpn_client_type_branch_connector": Denotes the Branch Connector client type. - 1: "zpn_client_type_zapp_partner": Denotes the Client Connector Partner client type. - 2: "zpn_client_type_ip_anchoring": Denotes the ZIA Service Edge client type. - 3: "zpn_client_type_zapp": Denotes the Client Connector client type. - 4: "zpn_client_type_eas_client": Denotes the Extranet client type. - 5: "zpn_client_type_vdi": Denotes the Client Connector for VDI client type. - 6: "zpn_client_type_edge_connector": Denotes the Cloud Connector client type. - 7: "zpn_client_type_machine_tunnel": Denotes the Machine Tunnel client type. - 8: "zpn_client_type_exporter": Denotes the Web Browser client type.
COUNTRY_CODE	"<country code>" (e.g., "US")	"true"
EDGE_CONNECTOR_GROUP	"<ID>"	"<Cloud Connector group ID>" (e.g., "257257305596685695"")
EXTRANET_LOCATION	"<Location ID or location group ID>" (e.g., "145259708813412201")	"Extranet Resource ID" (e.g., "145259708813412202")
EXTRANET_LOCATION_GROUP	"<Extranet Resource ID>" (e.g., "145259708813412201")	"<Extranet location group ID>" (e.g., "145259708813412203")
IDP	"<ID>"	<IdP ID> (e.g., "145259708813412532")
LOCATION	"<ID>"	<location ID> (e.g., "145259708813412273")
MACHINE_GRP	"<ID>"	<Machine group ID> (e.g., "144118148382065458")
PLATFORM	"<platform>" Supported values: - Windows (e.g., "windows") - Linux (e.g., "linux") - Android (e.g., "android") - iOS (e.g., "ios") - Mac (e.g., "mac")	"true"
POSTURE	<posture network ID> (e.g., "23b0d678b-180f-45ee-8b7d-82bff70f840b")	"true" or "false"
PRIVILEGE_PORTAL
RISK_FACTOR_TYPE	"ZIA"	Supported values: - "UNKNOWN" - "LOW" - "MEDIUM" - "HIGH" - "CRITICAL"
SAML	"<SAML attribute ID>" (e.g., "72057594038620864")	"<Attribute value to match>" (e.g., "Department")
SCIM	"<SCIM attribute ID>" (e.g. "72057594037988776")	"<Attribute value to match>" (e.g., "John Doe")
SCIM_GROUP	"<SCIM group attribute ID>" (e.g., "72057594037961373")	"<Attribute value to match>" (e.g., "20470")
TRUSTED_NETWORK	"<trusted network ID>"	"true"
WORKLOAD_TAG_GROUP	"<ID>"	"<workload group ID>" (e.g., "73214221214576058")

Getting a Particular Access Policy Rule Details

Before you get details for a particular access policy rule, you must get the policySetId captured in the Prerequisite API Call section.

To get details for a particular access policy rule:

1. Send a GET request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/policySet/{policySetId}/rule/{ruleId}.

2. Provide the following values in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • policySetId: The ID of the Global policy set captured in the Prerequisite API Call section.
   • ruleId: The ID of the rule you created in Creating a New Access Policy Rule section.

   For example: /mgmtconfig/v1/admin/customers/72057615512764416/policySet/72057615512764594/rule/72057615512764594.

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

Example Response

{
  "id":"72057615512764607",
  "creationTime":"1612396045",
  "modifiedBy":"72057615512764606",
  "name":"PolicyName",
  "description":"Description",
  "ruleOrder":"6",
  "priority":"1",
  "policyType":"1",
  "operator":"AND",
  "action":"ALLOW",
  "customMsg":"MsgString",
  "auditMessage":"{\"policyType\":\"Access Policy\",\"name\":\"PolicyName\",\"description\":\"Description\",\"action\":\"ALLOW\",\"ruleOrder\":\"6\",\"messageToUser\":\"MsgString\"}",
  "policySetId":"72057615512764421"
}

Updating an Access Policy Rule

To update the details of an access policy rule in the policy set:

1. Get the policySetId provided in Prerequisite API Call.

2. Use the entire JSON payload from Creating a New Access Policy Rule and send a PUT request to the following endpoint: /mgmtconfig/v2/admin/customers/{customerId}/policySet/{policySetId}/rule/{ruleId}.

3. Provide the following values in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • policySetId: The ID of the global policy set captured in Prerequisite API Call.
   • ruleId: The ID of the rule you created in Creating a New Access Policy Rule.

   For example: /mgmtconfig/v2/admin/customers/217316918451765248/policySet/217316918451765253/rule/217316918451766917.

NOTE

If the objectType value within the operands model is set to specific values (e.g., APP or APP_GROUP), then you must include attributes in the values model (i.e., an array of strings) inside each of the operands as well. If the objectType value within the operands model is set to specific values (e.g., POSTURE, SAML, SCIM, or SCIM_GROUP), then the entryValues property must be added to include the related lhs and rhs values. To learn more, see LHS and RHS Values.

A successful response returns code 204, meaning the access policy rule is updated. To learn more, see ZPA API Codes.

JSON Payload

{
    "policySetId": "72057594037928135",
    "id": "72057594038848450",
    "conditions": [
        {
            "operands": [
                {
                    "objectType": "APP",
                    "values": [
                        "72057594038619453"
                    ]
                },
                {
                    "objectType": "APP_GROUP",
                    "values": [
                        "72057594038619463"
                    ]
                }
            ]
        },
        {
            "operands": [
                {
                    "objectType": "SAML",
                    "entryValues": [
                        {
                            "lhs": "72057594038637267",
                            "rhs": "A"
                        }
                    ]
                }
            ],
            "operator": "OR"
        }
    ],
    "name": "Example Name",
    "description": "",
    "disabled": 0,
    "action": "ALLOW",
    "assistantGroups": [],
    "appServerGroups": [],
    "extranetEnabled": false,
    "extranetDTO": {},
    "customMsg": ""
}

PRA Support

To update an access policy rule with a required approval:

1. Send a PUT request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/policySet/{policySetId}/rule?microtenantId={microtenantId}.

2. Provide the following in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • policySetId: The ID of the global policy set captured in the Prerequisite API Call section.
   • microtenantId: The unique identifier of the Microtenant for the ZPA tenant. To learn more, see Configuring Microtenants Using API.

   For example: /mgmtconfig/v1/admin/customers/289370814522851328/policySet/289370814522851333/rule?microtenantId=145260601092866314.

3. Include the request headers to specify the following parameters about the request context:

   • Content-Type: application/json
   • Authorization: Bearer <access_token>

4. Use the following JSON payload and provide the following:

   • Ensure action is set to REQUIRE_APPROVAL
   • The policy criteria you want to include.

A successful response returns code 204, meaning the access rule is updated. To learn more, see ZPA API Codes.

JSON Payload

{
   "action":"REQUIRE_APPROVAL",
   "actionId":0,
   "appServerGroups":[
      {
         "configSpace":"DEFAULT",
         "creationTime":0,
         "description":"string",
         "enabled":true,
         "id":0,
         "learningEnabled":true,
         "modifiedBy":0,
         "modifiedTime":0,
         "name":"string",
         "restrictedEntity":true
      }
   ],
   "connectorGroups":[
      {
         "connectors":[
            {
               "applicationStartTime":0,
               "connectorGroupId":"string",
               "connectorGroupName":"string",
               "controlChannelStatus":"UNKNOWN",
               "creationTime":0,
               "ctrlBrokerName":"string",
               "currentVersion":"string",
               "description":"string",
               "enabled":true,
               "expectedUpgradeTime":0,
               "expectedVersion":"string",
               "fingerprint":"string",
               "id":0,
               "ipAcl":[
                  "string"
               ],
               "issuedCertId":0,
               "lastBrokerConnectTime":0,
               "lastBrokerConnectTimeDuration":"string",
               "lastBrokerDisconnectTime":0,
               "lastBrokerDisconnectTimeDuration":"string",
               "lastUpgradeTime":0,
               "latitude":0,
               "location":"string",
               "longitude":0,
               "modifiedBy":0,
               "modifiedTime":0,
               "name":"string",
               "nonceId":0,
               "nonceName":"string",
               "platform":"string",
               "platformDetail":"string",
               "previousVersion":"string",
               "privateIp":"string",
               "publicIp":"string",
               "restrictedEntity":true,
               "sargeVersion":"string",
               "signingCert":{
                  "additionalProp1":"string",
                  "additionalProp2":"string",
                  "additionalProp3":"string"
               },
               "upgradeAttempt":0,
               "upgradeStatus":"COMPLETE"
            }
         ],
         "cityCountry":"string",
         "countryCode":"string",
         "creationTime":0,
         "description":"string",
         "dnsQueryType":"IPV4_IPV6",
         "enabled":true,
         "geoLocationId":0,
         "id":0,
         "ipAcl":[
            "string"
         ],
         "latitude":"string",
         "location":"string",
         "longitude":"string",
         "modifiedBy":0,
         "modifiedTime":0,
         "name":"string",
         "overrideVersionProfile":true,
         "restrictedEntity":true,
         "serverGroups":[
            {
               "configSpace":"DEFAULT",
               "creationTime":0,
               "description":"string",
               "enabled":true,
               "id":0,
               "learningEnabled":true,
               "modifiedBy":0,
               "modifiedTime":0,
               "name":"string",
               "restrictedEntity":true
            }
         ],
         "lssAppConnectorGroup":true,
         "tcpQuickAckApp":true,
         "tcpQuickAckAssistant":true,
         "tcpQuickAckReadAssistant":true,
         "upgradeDay":"string",
         "upgradeTimeInSecs":"string",
         "versionProfileId":0,
         "versionProfileName":"string",
         "versionProfileVisibilityScope":"ALL"
      }
   ],
   "conditions":[
      {
         "creationTime":0,
         "id":0,
         "modifiedBy":0,
         "modifiedTime":0,
         "negated":true,
         "operands":[
            {
               "creationTime":0,
               "id":0,
               "idpId":0,
               "lhs":"string",
               "modifiedBy":0,
               "modifiedTime":0,
               "name":"string",
               "objectType":"USER",
               "rhs":"string"
            }
         ],
         "operator":"AND"
      }
   ],
   "creationTime":0,
   "customMsg":"string",
   "defaultRule":true,
   "defaultRuleName":"string",
   "description":"string",
   "id":0,
   "modifiedBy":0,
   "modifiedTime":0,
   "name":"string",
   "operator":"AND",
   "policySetId":0,
   "policyType":0,
   "priority":0,
   "reauthIdleTimeout":0,
   "reauthTimeout":0,
   "restrictedEntity":true,
   "ruleOrder":0,
   "zpnCbiProfileId":0,
   "zpnInspectionProfileId":0,
   "zpnInspectionProfileName":"string"
}

Example JSON Payload

{
   "policySetId":"289370814522851333",
   "conditions":[
      
   ],
   "name":"krishna-test1",
   "description":"krishna-test1",
   "action":"REQUIRE_APPROVAL",
   "connectorGroups":[
      
   ],
   "appServerGroups":[
      
   ],
   "customMsg":"krishna-test1"
}

Updating a Rule Order

To update a rule order:

1. Send a PUT request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/policySet/{policySetId}/rule/{ruleId}/reorder/{newOrder}.

2. Provide the following parameters in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • policySetId: The ID of the policy set.
   • ruleId: The ID of the rule.
   • newOrder: The new order of the rule.

   For example: /mgmtconfig/v1/admin/customers/72057594037927936/policySet/72057594037938994/rule/72057615512764641/reorder/4.

A successful response returns code 204, meaning the rule order is updated. To learn more, see ZPA API Codes.

NOTE

Updating the rule order of an access policy configured using Zscaler Deception is not supported. When changing the rule order of a regular access policy and there is an access policy configured using Deception, the rule order of the regular access policy must be greater than the rule order for an access policy configured using Deception.

Bulk Updating the Rule Order of All Rules in a Policy Set

To bulk update the rule order of all rules in a policy set:

1. Send a PUT request to the following endpoint: /mgmtconfig/v1/customers/{customerId}/policySet/{policySet}/reorder.

2. Provide the following in the request endpoint:

   • customerId: The ZPA tenant ID of the customer.
   • policySetId: The unique identifier of the policy set.

   For example: /mgmtconfig/v1/customers/217246660302995456/policySet/217246660303020009/reorder.

3. Use the following JSON payload and provide the new order of rule IDs for the rules in the policy set as an array of integers:

JSON Payload

[
   <ruleId1>,
   <ruleId2>,
   <ruleId3>
]

Example JSON Payload

[
   217316918451765311,
   217316918451765312,
   217316918451765310,
   217316918451765255
]

A successful response returns code 204, meaning the rules within the policy set are reordered.

Recommendations for Bulk Update

Zscaler recommends you are aware of the following when bulk updating the rule order of all rules within a policy set:

• A default rule exists for timeout policies, client forwarding policies, and isolation policies. This default rule cannot be reordered. For PUT requests to bulk update the rule order of timeout policies, client forwarding policies, and isolation policies, the rule ID of the last rule must be placed in the last index of input for the array of rule IDs. If the order of the default rule is changed from the last index, then the exception default.rule.reorder.notallowed - Reordering not allowed for default rule <ruleId> is returned.
• All rule IDs for the rules within the policy set must be included in the payload when making the request, otherwise error code 400 is returned with "reason" : “resource input length is not valid".
• If a rule ID from the policy set is missing from the array of rule IDs in the payload, the error missing.rule - Missing ruleIds: <ruleId1, ruleId2> from policySet <policySetId> is returned.
• If any invalid rule IDs are passed in the payload when making the request, error code 400 is returned with "reason": “The ruleId: <ruleId> does not belong to the policySetId: <policySetId>".
• If a rule in the policy set is a restricted entity (e.g., a rule configured using Deception) and its order is changed in the index of input for the array of rule IDs, then the error "reason": "Rule id <ruleId> is a restricted entity and cannot be reordered" is returned.

Deleting an Access Policy Rule

To delete an access policy rule:

1. Send a DELETE request to the following endpoint: /mgmtconfig/v1/admin/customers/{customerId}/policySet/{policySetId}/rule/{ruleId}.

2. Provide the following key-value pairs in the request body:

   • customerId: The ZPA tenant ID of the customer.
   • policySetId: The ID of the Global policySet captured in the Prerequisite API Call section.
   • ruleId: The ID of the rule you created in Creating a New Access Policy Rule section.

   For example: /mgmtconfig/v1/admin/customers/72057615512764416/policySet/72057615512764421/rule/72057615512764594.

A successful response returns code 204, meaning the access policy rule is deleted. To learn more, see ZPA API Codes.

NOTE

If an access policy is configured using Deception, then the update and delete options are unavailable.

Getting Details of All Client Types

To get details of all client types:

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

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

Example Response

{
 "zpn_client_type_exporter": "Web Browser",
 "zpn_client_type_exporter_noauth": "Web Browser Unauthenticated",
 "zpn_client_type_machine_tunnel": "Machine Tunnel",
 "zpn_client_type_edge_connector": "Cloud Connector",
 "zpn_client_type_zia_inspection": "ZIA Inspection",
 "zpn_client_type_zapp": "Client Connector",
 "zpn_client_type_slogger": "ZPA LSS",
 "zpn_client_type_browser_isolation": "Cloud Browser",
 "zpn_client_type_ip_anchoring": "ZIA Service Edge",
 "zpn_client_type_zapp_partner": "Client Connector Partner",
 "zpn_client_type_branch_connector": "Branch Connector",
 "zpn_client_type_vdi":"Client Connector for VDI"
}

Getting Platform Types for a Customer

To get the platform types for a customer:

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

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

Example Response

{
  "linux":"Linux",
  "android":"Android",
  "windows":"Windows",
  "ios":"iOS",
  "mac":"Mac"
}