--- title: API Calls slug: ps/help/en_us/nsa/22x/nsa-zta/api/api-calls createdAt: 2026-07-23T04:45:55.217Z --- This chapter describes the *Ivanti Neurons for Zero Trust Access* (*nZTA*) entities and the API calls that can be made to them. - Analytics, see [Analytics](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Applications, see [Applications (resources)](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Authentication Servers, see [Authentication Server (auth-servers)](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Device Policies, see [Device Policies (device-policy/groups)](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Device Policy Rules, see [Device Policy Rules (device-policy/rules)](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Gateways, see [Gateway (gateways)](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Gateway Settings, see [Gateway Settings](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Gateway Groups, see [Gateway Group (groups)](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Hostchecker Levels, see [Hostchecker Levels (hostchecker/levels)](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Hostchecker Products, see [Hostchecker Products (hostchecker/products)](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Resources, see "[Applications](docId\:aL8GMecutFpZ6Qlw5Cwfp)" and "[User Policies](docId\:aL8GMecutFpZ6Qlw5Cwfp)". - Resource Groups, see [Resource Group (resource-groups)](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Role Mapping Rules, see [Role Mapping Rules (role-mapping-rules)](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Secure Access Policies, see [Secure Access Policy (secure-access-policies)](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Enterprise Integrations Syslog Server Configuration, see [Enterprise Integrations Configurations Service (integrations/syslog)](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Users, see [Users (users)](docId\:aL8GMecutFpZ6Qlw5Cwfp). - User Rule Groups, see [User Rule Groups (user-rule-groups)](docId\:aL8GMecutFpZ6Qlw5Cwfp). - User Policies, see [User Policies (resources)](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Lockdown exceptions, see [Lockdown Exceptions](docId\:aL8GMecutFpZ6Qlw5Cwfp) - MDM Server, see [MDM Server](docId\:aL8GMecutFpZ6Qlw5Cwfp) - User Risk Score, see [User Risk Score](docId\:aL8GMecutFpZ6Qlw5Cwfp) - Storage Consumption. see [Storage Consumption](docId\:aL8GMecutFpZ6Qlw5Cwfp) For all calls, the following CURL command format uses the DSID cookie to query the REST API server: ```python curl -v --cookie "DSID=" ``` For a worked example of *nZTA* entity use, see [Ivanti Neurons for Zero Trust Access Use Case](docId\:L57zcVYzGiVv8r-cQNiG5). # Analytics The *analytics* resource provides API calls for components and elements within the **Insights** analytics pages of the Tenant Admin Portal. Analytics supports the following Network Overview activities: - Retrieving data for the Summary Ribbon, see [Retrieving Analytics Data for the Summary Ribbon](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the World Map Gateway Locations view, see [Retrieving Analytics Data for the World Map Gateway Location View](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the World Map Users view, see [Retrieving Analytics Data for the World Map Users View](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Sankey chart view, see [Retrieving Analytics Data for the Sankey Chart View](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Top Active Gateways chart, see [Retrieving Analytics Data for the Top Active Gateways Chart](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Top Active Applications chart, see [Retrieving Analytics Data for the Top Active Applications Chart](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Top Active User Locations chart, see [Retrieving Analytics Data for the Top Active User Locations Chart](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Active Anomalies chart, see [Retrieving Analytics Data for the Active Anomalies Chart](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Connected Clients Version chart, see [Retrieving Analytics Data for the Connected Clients Version Chart](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Non-compliances chart, see [Retrieving Analytics Data for the Non-compliances Chart](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Gateways Info-panel, see [Retrieving Analytics Data for the Gateways Info-panel](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Users Info-panel, see [Retrieving Analytics Data for the Users Info-panel](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Devices Info-panel, see [Retrieving Analytics Data for the Devices Info-panel](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Applications Info-panel, see [Retrieving Analytics Data for the Applications Info-panel](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Non-compliances Info-panel, see [Retrieving Analytics Data for the Non-compliances Info-panel](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Anomalies Info-panel, see [Retrieving Analytics Data for the Anomalies Info-panel](docId\:aL8GMecutFpZ6Qlw5Cwfp). The analytics resource also provides the following Logs activity: - Retrieving log data, see [Retrieving Log Data](docId\:aL8GMecutFpZ6Qlw5Cwfp). The analytics resource also provides the following Gateways activity: - Retrieving Gateway metrics, see [Retrieving Aggregated Gateway Statistics](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Admin Notifications, see [Retrieving Admin Notifications](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Alerts, see [Retrieving Alerts](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the DDR, see [Retrieving DDR Data](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Filter, see [Retrieving Filter](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Application Access Summary, see [Retrieving Application Access Summary](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Applications by Type, see [Retrieving Applications by Type](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Applications by Protocol, see [Retrieving Applications by Protocol](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Applications by Policy Name, see [Retrieving Applications by Policy Name](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Applications Access Trend, see [Retrieving Applications Access Trend](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Applications by App Group, see [Retrieving Applications by App Group](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Applications by Location, see [Retrieving Applications by Location](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Applications by Device Type, see [Retrieving Applications by Device Type](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Applications by Not Reachable, see [Retrieving Applications by Not Reachable](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Applications Health Details, see [Retrieving Applications Health Details](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Application Access by Device Type, see [Retrieving Application Access by Device Type](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Application Access by User Group, see [Retrieving Application Access by User Group](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Application Access by User Location, see [Retrieving Application Access by User Location](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Application Access Trend, see [Retrieving Application Access Trend](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Applications List, see [Retrieving Applications List](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving data for the Applications Details, see [Retrieving Applications Details](docId\:aL8GMecutFpZ6Qlw5Cwfp). ## Retrieving Analytics Data for the Summary Ribbon To retrieve a resource containing Summary Ribbon totals, use the REST API call below: - **Method:** POST /api/analytics/summary - **Resource:** Path - **JSON Data:** JSON data structure representing the **CommonFilterObject** schema (see [Schema](docId\:aL8GMecutFpZ6Qlw5Cwfp)) - containing date/time period selection, and optional filter for gateway selection. If processed correctly, a JSON body containing the *analytics/summary* entity is returned. Otherwise, a JSON body containing an error is returned. ### Schema The **CommonFilterObject** schema entity contains the following fields: |
`current_time` |
`integer`
`example: 1580515200`
`The time at which landing page was loaded. This is used to make sure that all the components on landing page have the same reference so that they summarize the same data set.` | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
`start_time` |
`integer example:`
`1580515200`
`Start time (epoch). This needs to be the starting time for the selected time_duration_type below. Selecting current day will result in displaying data from start of the current day (in UTC) e.g., - Selecting day for time_duration_type indicates this value should be start of the calendar day (in UTC)`
`* Selecting week for time_duration_type indicates this value should be start of the calendar week (in UTC)`
`* Selecting month for time_duration_type indicates this value should be start of the calender month (in UTC)`
`* When time_duration_type is active, the start_time will be ignored. Only (current_time) and (current_time - Active Window Period) will be considered as time duration` | |
`time_duration_type` |
`string`
`example: day`
`default: active`
`Details of what unit of time duration need to be considered for the data.`
`Enum:`
`[ active, current_day, day, week, month, last_24_hours, custom ]` | |
`timezone_offset` |
`integer`
`example: 330` | |
`gateway_type` |
`string`
`nullable: true`
`example: pcs`
`default: zta`
`Type of the gateway Enum: [ zta, pcs, pps, vtm ]` | |
`overlay_filter_type` |
`string example: non_compliance_users`
`Dashboard overlay text filter type`
`Enum:`
`[ connected_users_in_last_one_hour, non_compliance_users, connected_users_in_more_than_one_day, users_from_most_busy_gateway, users_from_least_busy_gateway, top_risky_users, geo_anomaly_users, user_roles_with_most_non_compliances, top_users_with_auth_failures, users_with_mfa ]` | |
`global_filter` |
`{`
`description: Global filter object that is applicable for all pages. If both overlay_filter_type and global_filter are set, only global_fiter would be used`
`gateway_ids Array [ string ]`
`example: List [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ]`
`default: List []`
`Filtering based on multiple gateway_ids.`
`}`
`nullable: true` | ### Request The following is an example request: ```python POST /api/analytics/summary Authorization: Content-Type: application/json Request Body { "current_time": 1648119483, "start_time": 1580515200, "time_duration_type": "active", "timezone_offset": 330, "gateway_type": "zta", "global_filter": { "gateway_ids": [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { [ { "actual_value": 3, "description": "Active users", "line_graph_color": "green", "line_graph_data": [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 3 ], "name": "users", "status": 0, "total_value": 1000, "trend_delta": 3, "trend_direction": "up" }, { "actual_value": 3, "description": "Active devices", "line_graph_color": "green", "line_graph_data": [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 3 ], "name": "devices", "status": 100, "total_value": 13, "trend_delta": 3, "trend_direction": "up" }, { "actual_value": 2, "description": "Active gateways", "line_graph_color": "green", "line_graph_data": [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 2 ], "name": "gateways", "status": 0, "total_value": 6, "trend_delta": 2, "trend_direction": "up" }, { "actual_value": 7, "description": "Active applications", "line_graph_color": "green", "line_graph_data": [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3, 4 ], "name": "applications", "status": 0, "total_value": 43, "trend_delta": 7, "trend_direction": "up" }, { "actual_value": 3, "description": "Non-compliances", "line_graph_color": "red", "line_graph_data": [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 3 ], "name": "non_compliance", "status": 100, "total_value": 3, "trend_delta": 3, "trend_direction": "up" }, { "actual_value": 13, "description": "Anomalies count", "line_graph_color": "red", "line_graph_data": [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 5, 0, 0, 0, 0, 4, 2, 0, 0, 0, 0, 0, 1, 0 ], "name": "anomalies", "status": 100, "total_value": 13, "trend_delta": 0, "trend_direction": "flat" } ] } ``` ## Retrieving Analytics Data for the World Map Gateway Location View To retrieve a resource containing gateway data-points plotted on a map overlay using geographic coordinates, use the REST API call below: - **Method:** POST /api/analytics/location\_view - **Resource:** Path - **JSON Data:** JSON data structure containing map overlay coordinates, date/time period selection, and optional filter for gateway selection. If processed correctly, a JSON body is returned that contains a list of data-points along with summary information and aggregated information. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/analytics/location_view Authorization: Content-Type: application/json Request Body { "top_left_lat": 23, "top_left_long": -12, "bottom_right_lat": -34, "bottom_right_long": 47, "current_time": 1648119483, "start_time": 1580515200, "time_duration_type": "active", "timezone_offset": 330, "gateway_type": "zta", "global_filter": { "gateway_ids": [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "response_type": "string", "bubble_items": [ { "status": 73, "granularity": "city", "city": "Austin", "country": "USA", "continent": "North America", "latitude": 48.5, "longitude": 71.923, "num_gws_good": 1, "num_gws_warning": 1, "num_gws_critical": 1, "num_gws_offline": 1, "active_users": {}, "active_devices": {}, "active_gateways": {}, "active_applications": {}, "num_deviations": {}, "non_compliance_count": {}, "critical_errors": {}, "id": "austin", "user_location_bubble_items": [ { "id": "bengaluru", "city": "bengaluru", "latitude": 48.5, "longitude": 71.923, "num_active_users": 10 "num_non_compliance_users": 0 } ] } ] } ``` ## Retrieving Analytics Data for the World Map Users View To retrieve a resource containing user data-points plotted on a map overlay using geographic coordinates, use the REST API call below: - **Method:** POST /api/analytics/zta\_users\_location\_view - **Resource:** Path - **JSON Data:** JSON data structure containing date/time period selection, and optional filter for gateway selection If processed correctly, a JSON body is returned that contains a list of data-points along with summary information. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/analytics/location_view Authorization: Content-Type: application/json Request Body { "current_time": 1580515200, "start_time": 1580515200, "time_duration_type": "day", "timezone_offset": 330, "gateway_type": "pcs", "overlay_filter_type": "non_compliance_users", "global_filter": { "gateway_ids": [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "count": 10, "bubble_items": [ { "granularity": "city", "city": "Austin", "country": "USA", "continent": "North America", "bubble_color": "Green", "latitude": 48.5, "longitude": 71.923, "avg_risk_score": { "count": 9, "color": "Green" }, "num_active_users": 176, "num_high_risk_users": 21, "num_moderate_risk_users": 9, "num_low_risk_users": 3, "num_no_risk_users": 0 } ] } ``` ## Retrieving Analytics Data for the Sankey Chart View To retrieve a resource containing data-points for plotting a Sankey chart of data flow between user groups, devices, Gateways, and applications, use the REST API call below: - **Method:** POST /api/analytics/sankey\_chart - **Resource:** Path - **JSON Data:** JSON data structure representing the **CommonFilterObject** schema (see [Schema](docId\:aL8GMecutFpZ6Qlw5Cwfp)) - containing date/time period selection, and optional filter for gateway selection. If processed correctly, a JSON body is returned that contains a list of data-points for plotting a Sankey chart. Otherwise, a JSON body containing an error is returned. ### Parameters - `max_items_per_pillar`: (integer - in: query) When this value \<= 0, all items in each pillar will be returned. Otherwise, only specified maximum number of items per pillar will be returned in response. Default: -1. - `apps_details`: (string - in: query) Flag capturing whether to return all apps or discovered apps details. Available values : all (default), discovered, non\_discovered, default\_gateway. ### Request The following is an example request: ```python POST /api/analytics/sankey_chart?max_items_per_pillar=-1&apps_details=all Authorization: Content-Type: application/json Request Body { "current_time": 1648119483, "start_time": 1580515200, "time_duration_type": "active", "timezone_offset": 330, "gateway_type": "zta", "global_filter": { "gateway_ids": [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "applications_list": [], "device_types_to_gateway_names": [ { "source": "Windows", "target": "blackthorn-bng-2", "value": 12 }, { "source": "Windows", "target": "az-bkthrn-eastus", "value": 4 } ], "gateway_names_to_application_names": [ { "source": "blackthorn-bng-2", "target": "amazon", "value": 4 }, { "source": "blackthorn-bng-2", "target": "atlassian", "value": 3 }, { "source": "blackthorn-bng-2", "target": "bngvc.bnglab.psecure.net", "value": 3 }, { "source": "az-bkthrn-eastus", "target": "juniper.net", "value": 3 }, { "source": "blackthorn-bng-2", "target": "rdp", "value": 1 }, { "source": "blackthorn-bng-2", "target": "telnetresource ip", "value": 1 }, { "source": "az-bkthrn-eastus", "target": "community.juniper.net", "value": 1 } ], "user_groups_to_device_types": [ { "source": "bng group", "target": "Windows", "value": 12 }, { "source": "sj group", "target": "Windows", "value": 4 } ] } ``` ## Retrieving Analytics Data for the Top Active Gateways Chart To retrieve a resource containing data used to create the top Active Gateways chart, use the REST API call below: - **Method:** POST /api/analytics/widgets/top\_gateways - **Resource:** Path - **JSON Data:** JSON data structure based on the **FilterObject** schema (see [Schema](docId\:aL8GMecutFpZ6Qlw5Cwfp)) - containing date/time period selection and optional filter for gateway selection. If processed correctly, a JSON body is returned that contains a list of data-points for plotting the Top Active Gateways chart. Otherwise, a JSON body containing an error is returned. ### Schema The **FilterObject** schema entity contains the following fields: |
`current_time` |
`integer`
`example: 1580515200 The time at which the Network Overview page was loaded. This is used to make sure that all the components on the page have the same reference so that they summarize the same data set.` | | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
`start_time` |
`integer example: 1580515200 The start time for the filter period (epoch). This value should represent the starting time for the selected 'time_duration_type'. Note the following:`
`* Selecting "day" for 'time_duration_type' indicates this value should be the start of a specific calendar day (in UTC) * Selecting "week" for 'time_duration_type' indicates this value should be the start of a specific calendar week (in UTC) * Selecting "month" for 'time_duration_type' indicates this value should be the start of a specific calender month (in UTC)` | |
`end_time` |
`integer example: 1580515200`
`The end time for the filter period (epoch). This value should represent the ending time for the selected 'time_duration_time' window. Use this field only when the 'time_duration_type' is set to "custom".` | |
`time_duration_type` |
`string example: day Details of what unit of time duration need to be considered for the data.`
`Enum:`
`[ active, current_day, day, week, month, last_24_hours, custom ]` | |
`timezone_offset` |
`string`
`nullable: true`
`example: pcs`
`default: zta Type of the gateway. Enum:`
`[ zta, pcs, pps, vtm, null ]` | |
`user_locations` |
`Array [ string ] example: List [ "Pune", "Bangalore" ] default: List [] User access location filters for queries. Filtering based on multiple locations is supported.` | |
`user_name` |
`string example: List [ "ZTAUser" ]`
`User name filter for queries.` | |
`period` |
`integer minimum: 0 default: 0 example: 0 Time-range in days (from current_time) for queries. 0 (default) means current values.` | | gateway\_names |
`Array [ string ] example: List [ "SanJose_Gateway_1", "Paris_Gateway_1" ]`
`default: List [] Names of the Gateways to be filtered.` | |
`application_names` |
`Array [ string ]`
`example: List [ "JIRA", "Confluence" ]`
`default: List [] Application name filters for queries.` | |
`application_name` |
`string`
`example: List [ "Confluence" ]` | |
`device_types` |
`Array [ string ] example: List [ "Windows", "iOS" ] default: List []Device type filters for queries.` | |
`geo_filter` |
`Array [ number ] example: List [ 90, -180, -90, 180 ]`
`default: List [ 90, -180, -90, 180 ] Geo filter; co-ordinates to be specified in this order [top_left_lat, top_left_long, bottom_right_lat, bottom_right_long]` | |
`location` |
`{ description: Optional location to filter records. granularity string default: city example: city Granularity of the location. Following fields will be set for different values of granularity: city - city, country, continent country - country, continent continent - continent Enum: [ city, country, continent ] city string example: Austin Name of the city. Set when granularity is city. country string example: USA Name of the country. Set when granularity is city or country. continent string example: North America Name of the continent. Set when granularity is city, country, or continent. }` | |
`overlay_filter_type` |
`string example: non_compliance_users`
`Dashboard overlay text filter type Enum: [ connected_users_in_last_one_hour, non_compliance_users, connected_users_in_more_than_one_day, users_from_most_busy_gateway, users_from_least_busy_gateway, top_risky_users, geo_anomaly_users, user_roles_with_most_non_compliances, top_users_with_auth_failures, users_with_mfa ]` | |
`global_filter` |
`{ description: Global filter object that is applicable for all pages. If both overlay_filter_type and global_filter are set, only global_fiter would be used gateway_ids Array [ string ] example: List [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] default: List [] Filtering based on multiple gateway_ids. } nullable: true` | ### Parameters - `num_gateways`: (integer - in: query) The maximum number of Gateways for which data is returned. Default: 10. ### Request The following is an example request: ```python POST /api/analytics/widgets/top_gateways?num_gateways=10 Authorization: Content-Type: application/json Request Body { "current_time": 1648119483, "start_time": 1580515200, "time_duration_type": "active", "timezone_offset": 330, "gateway_type": "zta", "global_filter": { "gateway_ids": [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "gateways": [ { "name": "blackthorn-bng-2", "value": 2 }, { "name": "az-bkthrn-eastus", "value": 1 } ], "title": "TOP GATEWAYS" } ``` ## Retrieving Analytics Data for the Top Active Applications Chart To retrieve a resource containing data used to create the top Active Applications chart, use the REST API call below: - **Method:** POST /api/analytics/widgets/top\_applications - **Resource:** Path - **JSON Data:** JSON data structure based on the **FilterObject** schema (see [Schema](docId\:aL8GMecutFpZ6Qlw5Cwfp)) - containing date/time period selection and optional filter for gateway selection. If processed correctly, a JSON body is returned that contains a list of data-points for plotting the Top Active Applications chart. Otherwise, a JSON body containing an error is returned. ### Parameters - `num_applications`: (integer - in: query) The maximum number of applications for which data is returned. Default: 10. ### Request The following is an example request: ```python POST /api/analytics/widgets/top_applications?num_applications=10 Authorization: Content-Type: application/json Request Body { "current_time": 1648119483, "start_time": 1580515200, "time_duration_type": "active", "timezone_offset": 330, "gateway_type": "zta", "global_filter": { "gateway_ids": [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "applications": [ { "name": "amazon", "value": 1 }, { "name": "atlassian", "value": 1 }, { "name": "bngvc.bnglab.psecure.net", "value": 1 }, { "name": "juniper.net", "value": 1 }, { "name": "community.juniper.net", "value": 1 }, { "name": "rdp", "value": 1 }, { "name": "telnetresource ip", "value": 1 } ], "title": "TOP APPLICATIONS" } ``` ## Retrieving Analytics Data for the Top Active User Locations Chart To retrieve a resource containing data used to create the Top Active User Locations chart, use the REST API call below: - **Method:** POST /api/analytics/widgets/top\_user\_access\_locations - **Resource:** Path - **JSON Data:** JSON data structure based on the **FilterObject** schema (see [Schema](docId\:aL8GMecutFpZ6Qlw5Cwfp)) - containing date/time period selection and optional filter for gateway selection. If processed correctly, a JSON body is returned that contains a list of data-points for plotting the Top Active User Locations chart. Otherwise, a JSON body containing an error is returned. ### Parameters - `granularity`: (string - in: query) The level of granularity for location identification. Available values : city (default), country, continent. - `num_locations`: (integer - in: query) The maximum number of locations for which data is returned. Default: 10. ### Request The following is an example request: ```python POST /api/analytics/widgets/top_user_access_locations?granularity=city&num_locations=10 Authorization: Content-Type: application/json Request Body { "current_time": 1648119483, "start_time": 1580515200, "time_duration_type": "active", "timezone_offset": 330, "gateway_type": "zta", "global_filter": { "gateway_ids": [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "title": "TOP USER ACCESS LOCATIONS", "user_access_locations": [ { "name": "bengaluru", "value": 2 }, { "name": "united states", "value": 1 } ] } ``` ## Retrieving Analytics Data for the Active Anomalies Chart To retrieve a resource containing data used to create the Active Anomalies chart, use the REST API call below: - **Method:** POST /api/analytics/widgets/anomalies - **Resource:** Path - **JSON Data:** JSON data structure based on the **FilterObject** schema (see [Schema](docId\:aL8GMecutFpZ6Qlw5Cwfp)) containing date/time period selection and optional filter for gateway selection. If processed correctly, a JSON body is returned that contains a list of data-points for plotting the Active Anomalies chart. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/analytics/widgets/anomalies Authorization: Content-Type: application/json Request Body { "current_time": 1648119483, "start_time": 1580515200, "time_duration_type": "active", "timezone_offset": 330, "gateway_type": "zta", "global_filter": { "gateway_ids": [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "buckets": [ { "name": "Business Hours", "value": 8 }, { "name": "Geolocation", "value": 5 } ], "chart_timestamp": 1648119483, "title": "Anomalies" } ``` ## Retrieving Analytics Data for the Connected Clients Version Chart To retrieve a resource containing data used to create the Connected Clients Version chart, use the REST API call below: - **Method:** POST /api/analytics/devices/connected\_clients - **Resource:** Path - **JSON Data:** JSON data structure based on the **FilterObject** schema (see [Schema](docId\:aL8GMecutFpZ6Qlw5Cwfp)) - containing date/time period selection and optional filter for gateway selection. If processed correctly, a JSON body is returned that contains a list of data-points for plotting the Connected Clients Version chart. Otherwise, a JSON body containing an error is returned. ### Parameters - `count`: (integer - in: query) Default: 5. ### Request The following is an example request: ```python POST /api/analytics/devices/connected_clients?count=5 Authorization: Content-Type: application/json Request Body { "current_time": 1648119483, "start_time": 1580515200, "time_duration_type": "active", "timezone_offset": 330, "users": "active", "gateway_type": "zta", "global_filter": { "gateway_ids": [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "chart_timestamp": 1648119483, "connected_devices": [ { "type": "Windows", "values": [ { "count": 2, "name": "9.1.14.14887" }, { "count": 1, "name": "9.1.12.8219" } ] } ], "title": "Pulse Client Versions" } ``` ## Retrieving Analytics Data for the Non-compliances Chart To retrieve a resource containing data used to create the Non-compliances chart, use the REST API call below: - **Method:** POST /api/analytics/users/top\_non\_compliance - **Resource:** Path - **JSON Data:** JSON data structure based on the **FilterObject** schema (see [Schema](docId\:aL8GMecutFpZ6Qlw5Cwfp)) - containing date/time period selection and optional filter for gateway selection. If processed correctly, a JSON body is returned that contains a list of data-points for plotting the Non-compliances chart. Otherwise, a JSON body containing an error is returned. ### Parameters - `count`: (integer - in: query) The number of Top Compliance policies for which data is needed based on the number of failures of the corresponding policy. A value of "-1" returns data for all Compliance policies. Default: 8. - `page_level`: (string - in: query) The Insights UI page level/depth for which non-compliance data is to be provided. Available values : L1, L2, L3, L4. ### Request The following is an example request: ```python POST /api/analytics/users/top_non_compliance?count=8&page_level=L1 Authorization: Content-Type: application/json Request Body { "current_time": 1648119483, "start_time": 1580515200, "time_duration_type": "active", "timezone_offset": 330, "gateway_type": "zta", "page_level": "L1" "global_filter": { "gateway_ids": [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "chart_timestamp": 1648119483, "non_compliance_policies": [ { "name": "antivirus", "value": 1 }, { "name": "commonpolicy", "value": 1 }, { "name": "symantecavlow", "value": 1 } ], "title": "Non-compliance" } ``` ## Retrieving Analytics Data for the Gateways Info-panel To retrieve a resource containing data used to populate the Gateways Info-panel, use the REST API call below: - **Method:** POST /api/analytics/widgets/top\_gateways/panel - **Resource:** Path - **JSON Data:** JSON data structure based on the **FilterObject** schema (see [Schema](docId\:aL8GMecutFpZ6Qlw5Cwfp)) - containing date/time period selection and optional filter for gateway selection. If processed correctly, a JSON body is returned that contains data used to populate the Gateways Info-panel. Otherwise, a JSON body containing an error is returned. ### Parameters - `max_panel_items`: (integer - in: query) The maximum number of items to be returned in the panel output. Default: 500. - `sort_order`: (string - in: query) The sort order to apply. Available values: asc, desc (default). - `sort_field`: (string - in: query) The field to sort by. Available values: active\_users\_count (default), active\_applications\_count, non\_compliance\_count, active\_devices\_count, active\_sessions\_count, number\_of\_issues, gateway\_name, city\_name. - `city_name`: (string - in: query) The selected city name. - `search_string`: (string - in: query) The search string to apply. - `status`: (string - in: query) Return all Gateways or only those Gateways with this specified status. Available values : all (default), active, offline, online, unregistered. ### Request The following is an example request: ```python POST /api/analytics/widgets/top_gateways/panel?max_panel_items=500&sort_order=desc&sort_field=active_users_count&city_name=bangalore&search_string=gateway1&status=all Authorization: Content-Type: application/json Request Body { "current_time": 1648532792, "start_time": 1580515200, "time_duration_type": "active", "timezone_offset": 330, "gateway_type": "zta", "global_filter": { "gateway_ids": [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "info_panel_items": [ { "id": "feicie-cneineoic-nfeie-32he", "gateway_name": "eng-mkn-gw-1", "city_name": "bangalore", "overall_color": "green", "gateway_status": "active", "number_of_issues": 10, "cpu_line_graph_data": "string", "memory_line_graph_data": "string", "disk_used_line_graph_data": "string", "active_users_count": 10, "active_devices_count": 10, "active_sessions_count": 10, "active_applications_count": 10, "non_compliance_count": 10, "issues_highest_severity": "CRITICAL", "issues_details": [ { "message_id": "NTP12456", "raw_message": "NTP server is not reachable", "issue_timestamp": 3848462926, "number_of_issues": 23 } ], "system_uptime": 10748, "last_config_update_timestamp": 1063264, "ssl_sessions_count": 10, "auth_only_sessions_count": 10, "active_sync_device_count": 10, "is_node_part_of_cluster": true, "cluster_properties": { "cluster_id": "9ccf22b9fe9ccf22b9fe", "cluster_name": "CoaGroup", "cluster_type": "Active/Active", "cluster_node_type": "active", "cluster_member_type": "leader", "is_vip_owner": false, "is_node_reachable": true, "is_node_enabled": false } } ], "count": 10, "all_gateway_count": 10, "active_gateway_count": 5, "offline_gateway_count": 5, "online_gateway_count": 5, "unregistered_gateway_count": 5 } ``` ## Retrieving Analytics Data for the Users Info-panel To retrieve a resource containing data used to populate the Users Info-panel, use the REST API call below: - **Method:** POST /api/analytics/widgets/top\_risky\_users/panel - **Resource:** Path - **JSON Data:** JSON data structure based on the **FilterObject** schema (see [Schema](docId\:aL8GMecutFpZ6Qlw5Cwfp)) - containing date/time period selection and optional filter for gateway selection. If processed correctly, a JSON body is returned that contains data used to populate the Users Info-panel. Otherwise, a JSON body containing an error is returned. ### Parameters - `offset`: (integer - in: query) The offset from which to fetch panel items. Default: 0. - `limit`: (integer - in: query) The maximum number of panel items to return. Default: 20. - `sort_order`: (string - in: query) The sort order to apply. Available values: asc, desc (default). - `sort_field`: (string - in: query) The field to sort by. Available values: user\_risk\_score (default), user\_name. - `city_name`: (string - in: query) The selected city name. - `search_string`: (string - in: query) :::Paragraph{indent="1"} The search string to apply. ::: ### Request The following is an example request: ```python POST /api/analytics/widgets/top_risky_users/panel?offset=0&limit=20&sort_order=desc&sort_field=user_risk_score&city_name=bangalore&search_string=user1&status=all Authorization: Content-Type: application/json Request Body { "current_time": 1648532792, "start_time": 1580515200, "time_duration_type": "active", "timezone_offset": 330, "gateway_type": "zta", "global_filter": { "gateway_ids": [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "info_panel_items": [ { "user_name": "user1", "timestamp": 1580515200, "user_risk_score": 256, "non_compliance_count": 25, "anomalies_count": 50, "activity_deviation_count": 25, "user_icon_color": "red", "device_location_city": "Austin" } ], "count": 10, "total": 20 } ``` ## Retrieving Analytics Data for the Devices Info-panel To retrieve a resource containing data used to populate the Devices Info-panel, use the REST API call below: - **Method:** POST /api/analytics/widgets/top\_device\_types/panel - **Resource:** Path - **JSON Data:** JSON data structure based on the **FilterObject** schema (see [Schema](docId\:aL8GMecutFpZ6Qlw5Cwfp)) - containing date/time period selection and optional filter for gateway selection. If processed correctly, a JSON body is returned that contains data used to populate the Devices Info-panel. Otherwise, a JSON body containing an error is returned. ### Parameters - `max_panel_items`: (integer - in: query) The maximum number of items to be returned in the panel output. Default: 500. - `sort_order`: (string - in: query) The sort order to apply. Available values: asc, desc (default). - `sort_field`: (string - in: query) The field to sort by. Available values: active\_users\_count (default), active\_applications\_count, non\_compliance\_count, deviations\_count, devices\_count. - `search_string`: (string - in: query) The search string to apply. ### Request The following is an example request: ```python POST /api/analytics/widgets/top_device_types/panel?max_panel_items=500&sort_order=desc&sort_field=active_users_count&search_string=Windows Authorization: Content-Type: application/json Request Body { "current_time": 1648532792, "start_time": 1580515200, "time_duration_type": "active", "timezone_offset": 330, "gateway_type": "zta", "global_filter": { "gateway_ids": [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "info_panel_items": [ { "nvt_items": [ { "name": "active_users_count", "trend": "Flat", "value": 2 }, { "name": "active_applications_count", "trend": "Flat", "value": 7 }, { "name": "devices_count", "trend": "Flat", "value": 2 }, { "name": "non_compliance_count", "trend": "Flat", "value": 3 }, { "name": "deviations_count", "trend": "Flat", "value": 0 } ], "status": 100, "sub_title": "", "title": "windows" } ] } ``` ## Retrieving Analytics Data for the Applications Info-panel To retrieve a resource containing data used to populate the Applications Info-panel, use the REST API call below: - **Method:** POST /api/analytics/widgets/top\_applications/panel - **Resource:** Path - **JSON Data:** JSON data structure based on the **FilterObject** schema (see [Schema](docId\:aL8GMecutFpZ6Qlw5Cwfp)) - containing date/time period selection and optional filter for gateway selection. If processed correctly, a JSON body is returned that contains data used to populate the Applications Info-panel. Otherwise, a JSON body containing an error is returned. ### Parameters - `max_panel_items`: (integer - in: query) The maximum number of items to be returned in the panel output. Default: 500. - `sort_order`: (string - in: query) The sort order to apply. Available values: asc, desc (default). - `sort_field`: (string - in: query) The field to sort by. Available values: active\_users\_count (default), active\_applications\_count, non\_compliance\_count, deviations\_count, devices\_count. - `search_string`: (string - in: query) The search string to apply. ### Request The following is an example request: ```python POST /api/analytics/widgets/top_applications/panel?max_panel_items=500&sort_order=desc&sort_field=active_users_count&search_string= Authorization: Content-Type: application/json Request Body { "current_time": 1648532792, "start_time": 1580515200, "time_duration_type": "active", "timezone_offset": 330, "gateway_type": "zta", "global_filter": { "gateway_ids": [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "info_panel_items": [ { "nvt_items": [ { "name": "active_users_count", "trend": "Flat", "value": 1 }, { "name": "active_applications_count", "trend": "Flat", "value": 1 }, { "name": "devices_count", "trend": "Flat", "value": 1 }, { "name": "application_type", "trend": "Flat", "value": 0 }, { "name": "application_port", "trend": "Flat", "value": 443 }, { "name": "non_compliance_count", "trend": "Flat", "value": 0 }, { "name": "deviations_count", "trend": "Flat", "value": 0 } ], "status": 0, "sub_title": "", "title": "pulsesecure.net" }, { "nvt_items": [ { "name": "active_users_count", "trend": "Flat", "value": 1 }, { "name": "active_applications_count", "trend": "Flat", "value": 1 }, { "name": "devices_count", "trend": "Flat", "value": 1 }, { "name": "application_type", "trend": "Flat", "value": 0 }, { "name": "application_port", "trend": "Flat", "value": 443 }, { "name": "non_compliance_count", "trend": "Flat", "value": 0 }, { "name": "deviations_count", "trend": "Flat", "value": 0 } ], "status": 0, "sub_title": "", "title": "community.juniper.net" }, ] } ``` ## Retrieving Analytics Data for the Non-compliances Info-panel To retrieve a resource containing data used to populate the Non-compliances Info-panel, use the REST API call below: - **Method:** POST /api/analytics/widgets/non\_compliance/panel - **Resource:** Path - **JSON Data:** JSON data structure based on the **FilterObject** schema (see [Schema](docId\:aL8GMecutFpZ6Qlw5Cwfp)) - containing date/time period selection and optional filter for gateway selection. If processed correctly, a JSON body is returned that contains data used to populate the Non-compliances Info-panel. Otherwise, a JSON body containing an error is returned. ### Parameters - `offset`: (integer - in: query) The offset from which to fetch panel items. Default: 0. - `limit`: (integer - in: query) The maximum number of panel items to return. Default: 20. - `sort_order`: (string - in: query) The sort order to apply. Available values: asc, desc (default). - `sort_field`: (string - in: query) The field to sort by. Available values: timestamp (default), user\_name. - `search_string`: (string - in: query) The search string to apply. ### Request The following is an example request: ```python POST /api/analytics/widgets/non_compliance/panel?offset=0&limit=20&sort_order=desc&sort_field=timestamp&search_string= Authorization: Content-Type: application/json Request Body { "current_time": 1648532792, "start_time": 1580515200, "time_duration_type": "active", "timezone_offset": 330, "gateway_type": "zta", "global_filter": { "gateway_ids": [ "74h4h3-u43943-4u3o4", "84h4h3-u43943-4u3o5" ] } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "count": 3, "info_panel_items": [ { "application_name": "Zendesk", "device_id": "b71af79efc6c43b2b7e9da58071a23da", "device_type": "Windows", "non_compliance_policy_name": "NetworkPolicy", "non_compliance_policy_types_list": [ "Network" ], "timestamp": 1648532547, "user_name": "cambridgetest1" }, { "application_name": "Salesforce", "device_id": "a1ee1dc5ee5e4263abaf91599f9dc595", "device_type": "Windows", "non_compliance_policy_name": "SymantecAVHigh", "non_compliance_policy_types_list": [ "HC" ], "timestamp": 1648532503, "user_name": "sjtest1" }, { "application_name": "Box", "device_id": "a1ee1dc5ee5e4263abaf91599f9dc595", "device_type": "Windows", "non_compliance_policy_name": "CommonPolicy", "non_compliance_policy_types_list": [ "Network", "HC" ], "timestamp": 1648532497, "user_name": "sjtest1" } ], "total": 3 } ``` ## Retrieving Analytics Data for the Anomalies Info-panel To retrieve a resource containing data used to populate the Anomalies Info-panel, use the REST API call below: - **Method:** POST /api/analytics/widgets/anomalies/panel - **Resource:** Path - **JSON Data:** JSON data structure representing the **AnomaliesPanelFilterObject** schema (see [Schema](docId\:aL8GMecutFpZ6Qlw5Cwfp)) - containing date/time period selection, and optional filter for gateway selection. If processed correctly, a JSON body is returned that contains data used to populate the Anomalies Info-panel. Otherwise, a JSON body containing an error is returned. ### Schema The **AnomaliesPanelFilterObject** schema entity contains the following fields: ```bash acknowledged_status string default: All example: Acknowledged Acknowledged status of anomalies to be filtered Enum: [ All, Acknowledged, Open ] ``` ### Parameters - `offset`: (integer - in: query) The offset from which to fetch panel items. Default: 0. - `limit`: (integer - in: query) The maximum number of panel items to return. Default: 20. - `sort_order`: (string - in: query) The sort order to apply. Available values: asc, desc (default). - `sort_field`: (string - in: query) The field to sort by. Available values: timestamp (default), user\_name, acknowledged. - `search_string`: (string - in: query) The search string to apply. ### Request The following is an example request: ```python POST /api/analytics/widgets/anomalies/panel?offset=0&limit=20&sort_order=desc&sort_field=timestamp&search_string=user1 Authorization: Content-Type: application/json Request Body { "acknowledged_status": "Acknowledged" } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "info_panel_items": [ { "anomaly_type": "GeoNewLocation", "user_name": "John Smith", "timestamp": 1587972453, "device_id": "27178d97948d46c09c205d30e9cf2afe", "session_id": "9ccf22b9fe", "device_type": "Windows", "anomaly_reason": "Non-familiar user location.", "anomaly_id": "e4abbb38ce8d4619891e561cedb7c807", "acknowledged": true, "active_session": true, "browser": "Google Chrome", "locations_history": [ { "location_name": "Bangalore", "timestamp": 1580515200 } ], "current_location": "Bangalore" }, {}, { "anomaly_type": "GeoNewLocation", "user_name": "John Smith", "timestamp": 1587972453, "device_id": "27178d97948d46c09c205d30e9cf2afe", "session_id": "9ccf22b9fe", "device_type": "Windows", "anomaly_reason": "Non-familiar user location.", "anomaly_id": "e4abbb38ce8d4619891e561cedb7c807", "acknowledged": true, "active_session": true, "browser": "Google Chrome", "application_names": [ "Microsoft", "Facebook" ], "details": "Normal access hours range of user is between 9 a.m. to 5 p.m." } ], "count": 20, "total": 20 } ``` ## Retrieving Log Data To retrieve a resource containing log data, use the REST API call below: - **Method:** POST /api/analytics/logs/search - **Resource:** Path - **JSON Data:** JSON data structure representing the **LogRequestEntity** schema (see [Schema](docId\:aL8GMecutFpZ6Qlw5Cwfp)), containing log selection criteria. If processed correctly, a JSON body is returned that contains log data. Otherwise, a JSON body containing an error is returned. ### Schema The **LogRequestEntity** schema entity contains the following fields: |
`name` |
`string`
`example: Filter1`
`Name to be used` | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
`start_time_es` |
`integer`
`example: 1576533928`
`Start time for logs in seconds since epoch. By default start of current day.` | |
`end_time_es` |
`integer example: 1576533928`
`End time for logs in seconds since epoch. By default current time i.e now.` | |
`current_time` |
`integer`
`example: 1576533928`
`Current time for logs in seconds since epoch. By default current time i.e now.` | |
`timezone_offset` |
`integer example: 330 Offset of the timezone to be used.` | |
`offset` |
`integer example: 0 Start offsets for logs, default is 0.` | |
`limit` |
`integer example: 100 Number of logs lines to be returned by the query` | | search\_string |
`string example: ZTA Search string to be used` | |
`search_string_columns` |
`Array [ string ] Selects search string columns to be used in query. Enum:`
`[ application_configured_name, application_discovered, application_group_names, application_host, application_id, application_ip, application_location_city, application_name, application_names, application_protocol, application_protocol_display_name, application_request_id, application_status, application_type, application_url, auth_server_name, pulse_client_version, device_location_city, device_id, device_model, device_os_type, device_os_version, device_type, gateway_location_city, gateway_id, gateway_name, gateway_type, message_id, message_type, non_compliance_policy_id, non_compliance_policy_name, non_compliance_policy_types_list, raw_message, realm_name, role_names, session_id, severity, sub_message_type, source_ip, user_group, user_groups_list, user_id, user_name, user_risk_score_category ]` | |
`sort_by` |
`string nullable: true default: timestamp Field used for sorting logs. Enum:`
`[ timestamp, source_ip, message_id, severity, gateway_id, gateway_name, session_id, user_name, device_id, raw_message, user_group, application_name, non_compliance_policy_name, non_compliance_policy_types_list, device_location_city, device_location_country, sub_message_type, user_risk_score, user_risk_score_category, user_anomalies_count, user_alerts_count, user_activity_deviations_count, acknowledged, device_type, realm_name, role_names, pulse_client_version, device_os_type, gateway_location_city, application_type, application_protocol, application_protocol_display_name, application_discovered, application_group_names, application_status, application_bookmark_type, application_connection_broker, application_desktop_protocol, application_host, application_ip, application_location_city, application_url, message, browser, browser_id, controller, message_type, bandwidth_consumed_str, connected_time, host_checker_policy_name, host_checker_failed_reason, session_duration, null ]` | |
`sort_group_by` |
`{ description: Field used for sorting of grouping logs. anyOf -> SortGroupByFieldType string example: application_name default: application_name Group by field type for sorting Enum: [ application_name, application_group, device_id, gateway_id, gateway_name, message_id, session_id,severity, source_ip, user_name, user_group, unique_application_group_names_count, unique_application_ips_count, unique_application_location_cities_count, unique_application_names_count, unique_application_protocols_count, unique_application_protocol_display_names_count, unique_application_urls_count, unique_device_ids_count, unique_device_location_cities_count, unique_gateway_ids_count, unique_gateway_names_count, unique_non_compliance_policy_types_count, unique_session_ids_count, unique_source_ips_count, unique_user_names_count, unique_user_groups_count ] }` | |
`group_by` |
`{ description: Field used for grouping logs. anyOf -> GroupFieldType string example: application_name default: application_name Group by field type Enum: [ application_discovered, application_group_names, application_ip, application_location_city, application_name, application_protocol, application_protocol_display_name, application_status, application_type, pulse_client_version, device_id, device_location_city, device_os_type, device_type, gateway_id, gateway_location_city, gateway_name, message_type, non_compliance_policy_name, non_compliance_policy_types_list, source_ip, session_id, severity, sub_message_type, user_name, user_group, user_risk_score_category ] }` | |
`order` |
`string default: desc Order of sorting specified by sortby field. Enum: [ asc, desc ]` | |
`log_type` |
`string default: access example: access Type of the logs to be exported Enum: [ access, admin, event ]` | |
`gateway_type` |
`string default: zta example: pcs Gateway Type of the logs to be exported Enum:`
`[ pcs, zta ]` | |
`columns` |
`Array [ LogColumns ] default: List [ "timestamp", "message_id", "severity", "session_id", "raw_message" ] Selects columns to be returned by query response. LogColumns string Enum:`
`[ acknowledged, adaptive_auth_reason, application_bookmark_type, application_connection_broker, application_desktop_protocol, application_discovered, application_group_names, application_host, application_ip, application_location_city, application_name, application_protocol, application_protocol_display_name, application_status, application_type, application_url, avg_cpu, avg_disk, avg_memory, avg_throughput, bandwidth_consumed_in_bytes, bandwidth_consumed_str, browser, browser_id, concurrent_users_sessions, connected_time, controller, cpu, device_id, device_location_city, device_location_country, device_os_type, device_type, disk_used_percentage, esap_version, esap_version, gateway_id, gateway_location_city, gateway_location_country, gateway_name, gateway_status, gateway_version, gateway_version, host_checker_failed_reason, host_checker_policy_name, is_session_active, max_concurrent_user_licenses_consumed, message, message_id, message_type, non_compliance_policy_name, non_compliance_policy_types_list, physical_memory, primary_auth_failed_reason, primary_auth_server_name, primary_auth_server_type, pulse_client_version, raw_message, realm_name, role_names, secondary_auth_failed_reason, secondary_auth_server_type, secondary_auth_server_name, secondary_auth_server_user_name, session_created_timestamp, session_duration, session_id, session_type, severity, source_ip, sub_message_type, swap_memory, throughput_value, timestamp, user_activity_deviations_count, user_alerts_count, user_anomalies_count, user_group, user_name, user_risk_score, user_risk_score_category, ALL, null ]` | |
`group_by_columns` |
`Array [ string ]`
`default: List [ "unique_gateway_names_count", "unique_user_names_count", "unique_application_names_count", "summary_device_types", "summary_message_types", "unique_device_ids_count", "unique_session_ids_count" ] Selects group by columns to be returned by query response. Enum: [ summary_acknowledged, summary_application_discovered, summary_application_names, summary_application_types, summary_application_status, summary_pulse_client_versions, summary_device_types, summary_device_os_types, summary_non_compliance_policy_names, summary_non_compliance_policy_types, summary_message_ids, summary_message_types, summary_severities, summary_sub_message_types, summary_application_bookmark_types, summary_application_desktop_protocols, summary_browsers, summary_esap_versions, summary_gateway_status, summary_gateway_versions, summary_is_session_actives, summary_user_risk_score_categories, unique_application_group_names_count, unique_application_ips_count, unique_application_location_cities_count, unique_application_names_count, unique_application_protocols_count, unique_application_protocol_display_names_count, unique_application_urls_count, unique_device_ids_count, unique_device_location_cities_count, unique_gateway_ids_count, unique_gateway_names_count, unique_session_ids_count, unique_source_ips_count, unique_user_names_count, unique_user_groups_count, unique_application_connection_brokers_count, unique_application_hosts_count, unqiue_device_ids_count, unique_device_location_countries_count, unique_gateway_location_cities_count, unique_host_checker_policy_names_count, unique_message_ids_count, unique_raw_messages_count, unique_role_names_count, unique_realm_names_count, max_user_activity_deviations_count, max_user_alerts_count, max_user_anomalies_count, max_user_risk_score, avg_user_activity_deviations_count, avg_user_alerts_count, avg_user_anomalies_count, avg_user_risk_score, avg_cpu, avg_disk_used_percentage, avg_swap_memory, avg_throughput_value, max_cpu, max_disk_used_percentage, max_swap_memory, max_throughput_value, recent_user_activity_deviations_count, recent_user_alerts_count, recent_user_anomalies_count, recent_user_risk_score, recent_user_risk_score_category, ALL ]` | |
`filters` |
`Array [ LogFilterEntity ] Represents a collection of filters to be applied. LogFilterEntity { description: Filter to be used filter_by* string example: message_ids Filter by field to be used Enum: [ gateway_ids, gateway_location_cities, gateway_names, user_names, user_groups, user_risk_score_categories, pulse_client_versions, device_ids, device_types, device_os_types, device_location_cities, device_location_countries, application_bookmark_types, application_connection_brokers, application_desktop_protocols, application_location_cities, application_names, application_group_names, application_hosts, application_ips, application_protocols, application_protocol_display_names, application_types, application_urls, message_ids, session_ids, source_ips, realm_names, role_names, severities, non_compliance_policy_names, non_compliance_policy_types, message_types, sub_message_types, ignore_sub_message_types, application_discovered, acknowledged, application_status_list, host_checker_policy_names, browsers, browser_ids, is_session_active, controller, raw_messages, gateway_statuses, gateway_versions, esap_versions, cpus, disk_used_percentages, physical_memories, swap_memories, throughput_values, avg_cpus, avg_disks, avg_memories, avg_throughputs, max_concurrent_user_licenses_consumed ] operator* string default: IS example: IS operator to be used Enum: [ IS, CONTAINS ] value* string example: ZTAGateway value to be checked for selected filter field }` | ### Request The following is an example request: ```python POST /api/analytics/logs/search Authorization: Content-Type: application/json Request Body { "name": "Filter1", "start_time_es": 1576533928, "end_time_es": 1576533928, "current_time": 1576533928, "timezone_offset": 330, "offset": 0, "limit": 100, "search_string": "ZTA", "search_string_columns": [ "application_configured_name" ], "sort_by": "timestamp", "sort_group_by": "application_name", "group_by": "application_name", "order": "desc", "log_type": "access", "gateway_type": "zta", "columns": [ "timestamp", "message_id", "severity", "session_id", "raw_message" ], "group_by_columns": [ "unique_gateway_names_count", "unique_user_names_count", "unique_application_names_count", "summary_device_types", "summary_message_types", "unique_device_ids_count", "unique_session_ids_count" ], "filters": [ { "filter_by": "message_ids", "operator": "IS", "value": "ZTAGateway" } ] } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "total": 1000, "count": 10, "offset": 0, "log_lines": [ { "timestamp": 1576533928, "message_id": "ADM24682", "gateway_id": "123e4567-e89b-12d3-a456-426655440000", "gateway_name": "Azure-Gateway_1", "severity": "INFO", "source_ip": "127.0.0.1", "raw_message": "Primary authentication successful for admindb/SDP Admin Auth from\n172.21.8.171\n", "user_name": "testuser1", "user_group": "testgroup1", "session_id": "fa0726e89c", "device_id": "965C34BA98C94F4EAE6F2D8564E6CEAC", "application_name": "Jira.abc.com", "application_group_names": [ [ "group-1", "group-2" ] ], "application_protocol": "HTTPS", "application_protocol_display_name": "Web", "application_discovered": false, "application_type": "url", "application_status": "Green", "application_connection_broker": "auto.pcs.com", "application_desktop_protocol": "ssh", "application_host": "auto.pcs.com", "application_ip": "1.2.3.4", "application_url": "www.gmail.com", "application_location_city": "Bengaluru", "application_bookmark_type": "Admin defined", "non_compliance_policy_name": "Jira_access_policy", "non_compliance_policy_types_list": [ [ "Location", "HC" ] ], "message_type": "Anomaly", "sub_message_type": "Anomaly", "pulse_client_version": "2021.12.1", "device_type": "Windows", "device_os_type": "Windows 10 Pro", "device_location_city": "mumbai", "user_risk_score": 10.23, "user_risk_score_category": "High", "user_alerts_count": 13, "user_anomalies_count": 10, "user_activity_deviations_count": 5, "acknowledged": true, "session_type": "local", "adaptive_auth_reason": "new_location", "controller": true, "is_session_active": true, "session_duration": "2:20:00", "bandwidth_consumed": 1024, "bandwidth_consumed_str": "1.00 Kb", "connected_time": "2:10:30", "role_names": [ [ "role-1", "role-2" ] ], "session_created_timestamp": 1576533928, "browser": "Google Chrome", "gateway_status": "online", "gateway_version": "21.x Build 1", "esap_version": "21.x Build 1", "cpu": 26.75, "physical_memory": 18.25, "swap_memory": 20.9, "disk_used_percentage": 34.5, "throughput_value": 67, "avg_cpu": 26.75, "avg_memory": 18.25, "avg_disk": 34.5, "avg_throughput": 67, "max_concurrent_user_licenses_consumed": 200 } ] } ``` ## Retrieving Aggregated Gateway Statistics To retrieve aggregated usage statistics for a list of Gateways, use the REST API call below: - **Method:** GET /api/analytics/apm/appstats - **Resource:** Path - **JSON Data:** None If processed correctly, a JSON body containing a *MetricsResponseEntity* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `metric`: ( array\[ string ] - in: query) A list of the required metrics. Available values: cpu, file\_hits, web\_hits, swap\_memory, physical\_memory, ssl\_connections, in\_in\_throughput\_bps, in\_out\_throughput\_bps, ext\_in\_throughput\_bps, ext\_out\_throughput\_bps, mul\_in\_throughput\_bps, mul\_out\_throughput\_bps, concurrent\_users\_sessions, concurrent\_users\_vpn\_sessions, disk\_used\_percentage, ALL. - `start_time_es`: (integer - in: query) Start time of aggregation since epoch in seconds. - `end_time_es`: (integer - in: query) End time of aggregation since epoch in seconds. - `bucket_size`: (string - in: query) Aggregation based on bucketing. Available values: 5minutes, hours, days. - `gateway_ids`: (array\[ string ] - in: query) A list of the Gateway ID(s) for which data is required. To request data for all Gateways, use the value 'ALL'. - `agg_type`: (string - in: query) The type of aggregation. Available values: SUM, AVG, MAX. - `location`: (string - in: query) The Gateway location to use. ### Request The following is an example request: ```python GET /api/analytics/apm/appstats?metric=cpu&start_time_es=1574973734&end_time_es=1574973777&bucket_size=5minutes&gateway_ids=74h4h3-u43943-4u3o4&agg_type=SUM&location=Bangalore Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "status": { "data_points": 0, "offset": 0, "agg_type": "SUM", "gateway_ids": [ "string" ] }, "chart_data": [ { "cpu": 23, "file_hits": 32, "web_hits": 13, "swap_memory": 33, "physical_memory": 56, "ssl_connections": 3423, "in_in_throughput_bps": 1334, "in_out_throughput_bps": 423423, "ext_in_throughput_bps": 423423, "ext_out_throughput_bps": 423423, "mul_in_throughput_bps": 423423, "mul_out_throughput_bps": 423423, "concurrent_users_sessions": 4213, "concurrent_users_vpn_sessions": 4213, "disk_used_percentage": 56, "timestamp_es": 0 } ] } ``` ## Retrieving Admin Notifications To retrieve admin notifications, use the REST API call below: - **Method:** GET api/v1/analytics/admin\_notifications - **Resource:** Path - **JSON Data:** None If processed correctly, a JSON body containing a *admin notifications* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `current_time`: (integer - in: query) current time of aggregation since epoch in seconds. - `gateway__type`: (string - in: query) Type of the gateway. ### Request The following is an example request: ```python curl -X 'GET' \ 'api/v1/analytics/admin_notifications/list?current_time=1576535635&gateway_type=zta' \ -H 'accept: application/json' ``` ### Response The following is an example response: ```python { "admin_name": "John", "last_login_time": 1576533928, "all_notifications": [ { "day_timestamp": 1576533928, "day_notifications": [ { "config_element_type": "User Role", "config_element_name": "Engineering Role", "config_element_operation": "MODIFIED", "number_of_gateways": 3 } ] } ] } ``` ## Retrieving Alerts To retrieve alerts, use the REST API call below: - **Method:** GET /api/v1/analytics/alerts - **Resource:** Path - **JSON Data:** None If processed correctly, a JSON body containing a *alerts* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `start_time_es`: (integer - in: query) Start time of aggregation since epoch in seconds. - `end_time_es`: (integer - in: query) End time of aggregation since epoch in seconds. - `current_time`: (integer - in: query) current time of aggregation since epoch in seconds. - `time_duration_type`: (string - in: query) Details of what unit of time duration need to be considered for the data. Available values : last\_1\_day, last\_7\_days, last\_15\_days, last\_30\_days - `offset`: (integer - in: query) Start offsets for alerts, default is 0. - `limit`: (integer - in: query) Number of alerts to be returned by the query. - `source_type`: (string - in: query) Field used for filtering by source\_type. - `sort_by`: (string - in: query) Field used for sorting logs. By default time stamp. - `order`: (string - in: query) Oder of sorting specified by sortby field. - `severities`: (string - in: query) severity filter for selecting alerts based on severity. - `types`: (array\[ string ] - in: query) Types filter for selecting alerts based on type(s). - `columns`: (array\[ string ] - in: query) Selects columns to be returned by query response. ### Request The following is an example request: ```python curl -X 'GET' \ 'api/v1/analytics/alerts/list?start_time_es=1576533928&end_time_es=1576535635¤t_time=1576535635&time_duration_type=last_1_day&offset=0&limit=100&source_type=pzt_gateway&sort_by=timestamp&order=desc&severities=information&types=Gateway%20upgrade&columns=severity&columns=timestamp&columns=type&columns=target&columns=message_type&columns=source_name' \ -H 'accept: application/json' ``` ### Response The following is an example response: ```python { "total": 0, "items": [ { "severity": "string", "timestamp": 1576533928, "type": "Gateway upgrade", "target": "PZTGateway", "source_name": "my-pcs-gateway", "message_type": "The gateway upgrade completed" } ] } ``` ## Retrieving DDR Data To retrieve DDR data, use the REST API call below: - **Method:** GET api/v1/analytics/ddr - **Resource:** Path - **JSON Data:** None If processed correctly, a JSON body containing a *ddr* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `offset`: (integer - in: query) Start offsets for devices, default is 0. - `limit`: (integer - in: query) Number of devices to be returned by the query, default is 100. - `sort_by`: (string - in: query) Field used for sorting device details. By default last\_seen. - `order`: (string - in: query) Oder of sorting specified by sort by field. ### Request The following is an example request: ```python curl -X 'GET' \ 'api/v1/analytics/ddr/table?offset=0&limit=100&sort_by=last_seen&order=desc' \ -H 'accept: application/json' ``` ### Response The following is an example response: ```python { "total": 1000, "count": 10, "offset": 0, "device_details": 0 } ``` ## Retrieving Filter To retrieve list of values of the requested type satisfying the requested search, use the REST API call below: - **Method:** GET /api/v1/analytics/filter\_suggestions - **Resource:** Path - **JSON Data:** None If processed correctly, a JSON body containing a *filter\_suggestions* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `search`: (string - in: query) Search to filter the list of filter values. - `filter_type`: (string - in: query) Type of values desired. ### Request The following is an example request: ```python curl -X 'GET' \ 'api/v1/analytics/filter_suggestions/list?search=Al&filter_type=user_group' \ -H 'accept: application/json' ``` ### Response The following is an example response: ```python [ [ "Alice", "Bob" ] ] ``` ## Retrieving Application Access Summary To retrieve table summary details of applications accessed, use the REST API call below: - **Method:** GET api/v1/analytics/applications/summary\_table - **Resource:** Path - **JSON Data:** None If processed correctly, a JSON body containing a *summary table* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `start_time_es`: (integer - in: query) Start time of aggregation since epoch in seconds. - `end_time_es`: (integer - in: query) End time of aggregation since epoch in seconds. - `current_time`: (integer - in: query) current time of aggregation since epoch in seconds. - `time_duration_type`: (string - in: query) Details of what unit of time duration need to be considered for the data. - `offset`: (integer - in: query) Start offsets for alerts, default is 0. - `limit`: (integer - in: query) Number of alerts to be returned by the query. - `sort_by`: (string - in: query) Field used for sorting logs. By default time stamp. - `order`: (string - in: query) Oder of sorting specified by sortby field. - `application_names`: (array\[ string ]- in: query) application name filter, for selecting logs based on application\_name(s). - `gateway_names`: (array\[ string ]- in: query) gateway name filter, for selecting logs based on gateway\_name(s). - `user_names`: (array\[ string ] - in: query) user name filter, for selecting logs based on user\_name(s). - `user_locations`: (array\[ string ] - in: query) user location based filter, for selecting logs based on user location(s). - `device_ids`: (array\[ string ] - in: query) device\_id based filter, for selecting logs based on device\_id(s). - `device_types`: (array\[ string ] - in: query) device\_type based filter, for selecting logs based on device\_type(s). - `non_compliance_policy_names`: (array\[ string ] - in: query) name of the policy which marked the access as non-compliance. - `user_groups`: (array\[ string ] - in: query) user group filter, for selecting logs based on user\_group(s). - `columns`: (array\[ string ] - in: query) Selects columns to be returned by query response. ### Request The following is an example request: ```python curl -X 'GET' \ 'api/v1/analytics/applications/summary_table?start_time_es=1576533928&end_time_es=1576535635¤t_time=1576535635&offset=0&limit=100&sort_by=application_name&order=asc&application_names=salesforce&gateway_names=PZTGateway&user_names=system&user_locations=Bangalore&device_ids=965C34BA98C94F4EAE6F2D8564E6CEAC&device_types=Windows&non_compliance_policy_names=Symantec%20AV%20policy&user_groups=Engineering&columns=application_id&columns=application_name&columns=application_port&columns=application_type&columns=application_protocol&columns=application_protocol_display_name&columns=gateway_name&columns=users_count&columns=devices_count&columns=locations_count&columns=access_count&columns=non_compliance_count' \ -H 'accept: application/json' ``` ### Response The following is an example response: ```python { "total": 0, "items": [ { "application_id": "1e089202204743639b68864584d5af8a", "application_name": "Salesforce", "application_port": 80, "application_type": "FQDN", "application_protocol": "HTTPS", "application_protocol_display_name": "Web", "gateway_name": "PZTGateway", "users_count": 5, "devices_count": 10, "locations_count": 8, "access_count": 20, "non_compliance_count": 4, "application_discovered": false } ] } ``` ## Retrieving Applications by Type To retrieve count for Application Type chart using filters object as input, use the REST API call below: - **Method:** POST api/v1/analytics/applications/applications\_by\_type - **Resource:** Path - **JSON Data:** None If processed correctly, a JSON body containing a *applications\_by\_type* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `apps_details`: (string - in: query) Flag capturing whether to return all apps or discovered apps details. ### Request The following is an example request: ```python curl -X 'POST' \ 'api/v1/analytics/applications/applications_by_type?apps_details=all' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '"string"' ``` ### Response The following is an example response: ```python List of datapoints to be shown in Application Type chart. ``` ## Retrieving Applications by Protocol To retrieve count for Application Protocol chart using filters object as input, use the REST API call below: - **Method:** POST https\://editor.swagger.io/api/v1/analytics/applications/applications\_by\_protocol - **Resource:** Path - **JSON Data:** None If processed correctly, a JSON body containing a *applications\_by\_protocol* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `count`: (integer - in: query) Number of top application protocol access counts for which data is needed. Passing '-1' will return data for all application protocol access details. - `apps_details`: (string - in: query) Flag capturing whether to return all apps or discovered apps details.. ### Request The following is an example request: ```python curl -X 'POST' \ 'api/v1/analytics/applications/applications_by_protocol?count=8&apps_details=all' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '"string"' ``` ### Response The following is an example response: ```python List of datapoints to be shown in Application Protocol chart. ``` ## Retrieving Applications by Policy Name To retrieve count for Application Policy Name chart using filters object as input, use the REST API call below: - **Method:** POST api/v1/analytics/applications/applications\_by\_policy\_name - **Resource:** Path - **JSON Data:** None - If processed correctly, a JSON body containing a *applications\_by\_policy\_name* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `count`: (integer - in: query) Number of top application policy names counts for which data is needed. Passing '-1' will return data for all application policy names details. - `apps_details`: (string - in: query) Flag capturing whether to return all apps or discovered apps details.. ### Request The following is an example request: ```python curl -X 'POST' \ 'api/v1/analytics/applications/applications_by_policy_name?count=8&apps_details=all' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '"string"' ``` ### Response The following is an example response: ```python List of datapoints to be shown in Application Policy Name chart. ``` ## Retrieving Applications Access Trend To retrieve top n number of applications access trend using filters object as input, use the REST API call below: - **Method:** POST api/v1/analytics/applications/applications\_access\_trend - **Resource:** Path - **JSON Data:** None - If processed correctly, a JSON body containing a *applications\_access\_trend* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `count`: (integer - in: query) Number of applications to be considered for returning access trend. Passing '-1' will return data for all applications access trend. - `bar_graph`: (query) Type of bar graph to be shown in Access Trend chart. - `apps_details`: (string - in: query) Flag capturing whether to return all apps or discovered apps details.. ### Request The following is an example request: ```python curl -X 'POST' \ 'api/v1/analytics/applications/applications_access_trend?count=10&apps_details=all' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '"string"' ``` ### Response The following is an example response: ```python Data points to be shown in Access Trend chart. ``` ## Retrieving Applications by App Group To retrieve counts for Applications by App Group chart using filters object as input, use the REST API call below: - **Method:** POST api/v1/analytics/applications/applications\_access\_trend - **Resource:** Path - **JSON Data:** None - If processed correctly, a JSON body containing a *applications\_access\_trend* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `count`: (integer - in: query) Number of top application accessed by app group for which data is needed. Passing '-1' will return data for all applications accessed by app group details. - `apps_details`: (string - in: query) Flag capturing whether to return all apps or discovered apps details.. ### Request The following is an example request: ```python curl -X 'POST' \ 'api/v1/analytics/applications/applications_by_app_group?count=8&apps_details=all' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '"string"' ``` ### Response The following is an example response: ```python List of datapoints to be shown in Applications by app group chart. ``` ## Retrieving Applications by Location To retrieve counts for Applications by location chart using filters object as input, use the REST API call below: - **Method:** POST api/v1/analytics/applications/applications\_by\_location - **Resource:** Path - **JSON Data:** None - If processed correctly, a JSON body containing a *applications\_by\_location* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `count`: (integer - in: query) Number of top application accessed by location for which data is needed. Passing '-1' will return data for all applications accessed by location details. - `apps_details`: (string - in: query) Flag capturing whether to return all apps or discovered apps details.. ### Request The following is an example request: ```python curl -X 'POST' \ 'api/v1/analytics/applications/applications_by_location?count=8&apps_details=all' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '"string"' ``` ### Response The following is an example response: ```python List of datapoints to be shown in Applications by location chart. ``` ## Retrieving Applications by Device Type To retrieve counts for Applications by Device Type chart using filters object as input, use the REST API call below: - **Method:** POSTapi/v1/analytics/applications/applications\_by\_device\_type - **Resource:** Path - **JSON Data:** None - If processed correctly, a JSON body containing a *applications\_\_by\_device\_type* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `count`: (integer - in: query) Number of top application accessed by device type for which data is needed. Passing '-1' will return data for all applications accessed by device type details. - `apps_details`: (string - in: query) Flag capturing whether to return all apps or discovered apps details.. ### Request The following is an example request: ```python curl -X 'POST' \ 'api/v1/analytics/applications/applications_by_device_type?count=8&apps_details=all' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '"string"' ``` ### Response The following is an example response: ```python List of datapoints to be shown in Applications by Device Type chart. ``` ## Retrieving Applications by Not Reachable To retrieve counts for Applications by Not Reachable chart using filters object as input, use the REST API call below: - **Method:** POSTapi/v1/analytics/applications/applications\_by\_not\_reachable - **Resource:** Path - **JSON Data:** None - If processed correctly, a JSON body containing a *applications\_by\_not\_reachable* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `count`: (integer - in: query) Number of top not reachable applications for which data is needed. Passing '-1' will return data for all not reachable applications. - `apps_details`: (string - in: query) Flag capturing whether to return all apps or discovered apps details. ### Request The following is an example request: ```python curl -X 'POST' \ 'api/v1/analytics/applications/applications_by_not_reachable?count=8&apps_details=all' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '"string"' ``` ### Response The following is an example response: ```python List of datapoints to be shown in Not Reachable Applications chart. ``` ## Retrieving Applications Health Details To retrieve health details of the applications, use the REST API call below: - **Method:** GET api/v1/analytics/applications/health\_details - **Resource:** Path - **JSON Data:** None - If processed correctly, a JSON body containing a *health\_details* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `application_ids`: (string - in: query) App Ids. ### Request The following is an example request: ```python curl -X 'GET' \ 'api/v1/analytics/applications/health_details' \ -H 'accept: application/json' ``` ### Response The following is an example response: ```python { "count": 1, "details": [ { "application_id": "1e089202204743639b68864584d5af8a", "application_name": "ZTAApplication", "health_status": "grey", "messages": [ "application is reachable", "application is not reachable" ] } ] } ``` ## Retrieving Application Access by Device Type To retrieve counts for Application Access by Device Type chart on application L3 page using filters object as input (including Application Name), use the REST API call below: - **Method:** POST api/v1/analytics/applications/application\_access\_by\_device\_type - **Resource:** Path - **JSON Data:** None - If processed correctly, a JSON body containing a *application\_access\_by\_device\_type* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `count`: (integer - in: query) Number of top application accessed by device type for which data is needed. Passing '-1' will return data for all applications accessed by device type details. ### Request The following is an example request: ```python curl -X 'POST' \ 'api/v1/analytics/applications/application_access_by_device_type?count=10' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '"string"' ``` ### Response The following is an example response: ```python List of datapoints to be shown in Applications Accesses by Device Type chart. ``` ## Retrieving Application Access by User Group To retrieve counts for Application Access by User Group chart using filters object as input (including Application Name), use the REST API call below: - **Method:** POST api/v1/analytics/applications/application\_access\_by\_user - **Resource:** Path - **JSON Data:** None - If processed correctly, a JSON body containing a *application\_access\_by\_user* resource is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python curl -X 'POST' \ 'api/v1/analytics/applications/application_access_by_user' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '"string"' ``` ### Response The following is an example response: ```python List of datapoints to be shown in Applications Accesses by User Group chart. ``` ## Retrieving Application Access by User Location To retrieve counts for Application Access by User Location chart using filters object as input (including Application Name), use the REST API call below: - **Method:** POST api/v1/analytics/applications/application\_access\_by\_user\_location - **Resource:** Path - **JSON Data:** None - If processed correctly, a JSON body containing a *application\_access\_by\_user\_location* resource is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python curl -X 'POST' \ 'api/v1/analytics/applications/application_access_by_user_location' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '"string"' ``` ### Response The following is an example response: ```python List of datapoints to be shown in Applications Accesses by User Location chart. ``` ## Retrieving Application Access Trend To retrieve application access trend using filters object as input (including Application Name), use the REST API call below: - **Method:** POST api/v1/analytics/applications/application\_access\_trend - **Resource:** Path - **JSON Data:** None - If processed correctly, a JSON body containing a *application\_access\_trend* resource is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python curl -X 'POST' \ 'api/v1/analytics/applications/application_access_trend' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '"string"' ``` ### Response The following is an example response: ```python { "chart_timestamp": 1580515200, "title": "Application Access Trend", "access_chart_data": [ "string" ] } ``` ## Retrieving Applications List To retrieve list of applications, whose name starts with the given prefix, use the REST API call below: - **Method:** GET api/v1/analytics/applications/applications\_list - **Resource:** Path - **JSON Data:** None - If processed correctly, a JSON body containing a *applications\_list* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `prefix`: (string - in: query) Prefix of the application name. ### Request The following is an example request: ```python curl -X 'GET' \ 'api/v1/analytics/applications/applications_list?prefix=mkn' \ -H 'accept: application/json' ``` ### Response The following is an example response: ```python { "applications_list": [ [ "app1", "app2", "app3" ] ] } ``` ## Retrieving Applications Details To retrieve details of user for given application name, use the REST API call below: - **Method:** GET api/v1/analytics/applications/application\_details - **Resource:** Path - **JSON Data:** None - If processed correctly, a JSON body containing a *application\_details* resource is returned. Otherwise, a JSON body containing an error is returned. ### Parameters - `name`: (string - in: query) Name of the application. ### Request The following is an example request: ```python curl -X 'GET' \ 'api/v1/analytics/applications/application_details?name=Salesforce' \ -H 'accept: application/json' ``` ### Response The following is an example response: ```python { "name": "ZTA-Application-" } ``` # Applications (resources) An application is a type of *resources* entity that represents a *nZTA* application. Applications support the following activities: - Retrieving all applications, see [Retrieving an Application](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Editing an application, see [Editing an Application](docId\:aL8GMecutFpZ6Qlw5Cwfp). :::hint{type="info" indent="1"} The *resources* entity is also used to represent a *nZTA* user policy. This is enabled by a **type** of "sign-in", see [User Policies (resources](docId\:aL8GMecutFpZ6Qlw5Cwfp)). ::: ## Retrieving an Application To retrieve all application (*resources*) entities, use the REST API call below: - **Method:** GET /api/v1/policies/resources - **Resource:** Path - **JSON Data:** JSON dictionary representing a *resources* type of "application". If processed correctly, a JSON body containing a list of all application resources is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python GET /api/v1/policies/resources Authorization: Content-Type: application/json Request Body { "type": "application" } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "type": "application", "name": "app1", "description": "app1", "app_config": { "access_type": "saml", "name": "app1", "resource": "https://www.example.com", "resource_type": "url", "bookmark_config": { "name": "app1", "type": "web", "description": "app1", "launch_window": True, "url": "https://www.example.com", "icon": "/admin/static/media/filename.svg" }, "saml_config": { "sp_metadata": "string" } } } ``` ## Editing an Application To edit an application *resources* entity, use the REST API call below: - **Method:** PUT /api/v1/policies/resources/ - **Resource:** Path - **JSON Data:** JSON dictionary representing changed properties for an application *resources* entity. If processed correctly, a JSON body containing the updated application *resources* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python PUT /api/v1/policies/resources/{resource_id} Authorization: Content-Type: application/json Request Body { "type": "application", "name": "app1", "description": "app1", "app_config": { "access_type": "saml", "name": "app1", "resource": "https://www.example.com", "resource_type": "url", "bookmark_config": { "name": "app1", "type": "web", "description": "app1", "launch_window": True, "url": "https://www.intuit.com", "icon": "/admin/static/media/filename.svg" }, "saml_config": { "sp_metadata": "string" } } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "type": "application", "name": "app1", "description": "app1", "app_config": { "access_type": "saml", "name": "app1", "resource": "https://www.example.com", "resource_type": "url", "bookmark_config": { "name": "app1", "type": "web", "description": "app1", "launch_window": True, "url": "https://www.example.com", "icon": "/admin/static/media/filename.svg" }, "saml_config": { "sp_metadata": "string" } } } ``` # Authentication Server (auth-servers) The *auth-servers* entity represents a *nZTA* authentication server. Authentication servers support the following activities: - Retrieving All Authentication Servers, see [Retrieving All Authentication Servers](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Creating a Local Authentication Server, see [Creating a Local Authentication Server](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Creating a SAML Authentication Server, see [Creating a SAML Authentication Server](docId\:aL8GMecutFpZ6Qlw5Cwfp). ## Retrieving All Authentication Servers To retrieve all *auth-servers* entities, use the REST API call below: - **Method:** GET /api/v1/policies/auth-servers - **Resource:** Path - **JSON Data:** No JSON is required for this request. If processed correctly, a JSON body containing a list of all auth-servers is returned. Otherwise, a JSON body containing an error is returned. ### Request This REST API command always retrieves all *auth-servers* entities. The following is an example request: ```bash GET /api/v1/policies/auth-servers Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "total": 0, "auth_servers": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Local", "name": "string" }, { "id": "2c963f64-5717-4562-b3fc-2c963f66afa6", "type": "Local", "name": "string" }, { "id": "66afa664-5717-4562-b3fc-2c963f66afa6", "type": "Local", "name": "string" }, { "id": "63f66a64-5717-4562-b3fc-2c963f66afa6", "type": "Local", "name": "string" } ] } ``` ## Creating a Local Authentication Server To create a local authentication server: - **Method:** POST /api/v1/policies/auth-servers - **Resource:** Path - **JSON Data:** JSON dictionary representing a new local *auth-servers* entity. If processed correctly, a JSON body containing the new local *auth-servers* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/v1/policies/auth-servers Authorization: Request Body { "type": "Local", "name": "string", "cert_config": { "user_name_template": "string" }, "local_config": { "users": [ { "name": "string", "full_name": "string", "password": "string", "password_change_required": true } ] }, "samlsp_config": { "metadata_config_type": "url", "metadata_config_url": "string", "idp_type": "Azure AD", "idp_metadata_xml": "string" } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Local", "name": "string", "cert_config": { "user_name_template": "string" }, "samlsp_config": { "metadata_config_type": "url", "metadata_config_url": "string", "idp_type": "Azure AD", "idp_metadata_xml": "string" } } ``` ## Creating a SAML Authentication Server To create a remote SAML authentication server: - **Method:** POST /api/v1/policies/auth-servers - **Resource:** Path - **JSON Data:** JSON dictionary representing a new SAML *auth-servers* entity. If processed correctly, a JSON body containing the new SAML *auth-servers* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/v1/policies/auth-servers Authorization: Request Body { "type": "SAML (Azure AD)", "name": "auth_server_1", "samlsp_config": { "idp_metadata_xml": "string" "idp_type": "Azure AD", "metadata_config_type": "file", "metadata_config_url": "string", } } ``` ### Response The following is an example response: ```r HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "ab45c43278b42312f00fab4321af54c0543b", "type": "SAML (Azure AD)", "name": "auth_server_1", "samlsp_config": { "idp_metadata_xml": "string" "idp_type": "Azure AD", "metadata_config_type": "file", "metadata_config_url": "string", } } ``` # Device Policies (device-policy/groups) The *device-policy/groups* entity represents a *nZTA* device policy configuration. :::hint{type="info"} Hostchecker levels must be created and configured before device policies can be created successfully, see [Hostchecker Levels (hostchecker/levels)](docId\:aL8GMecutFpZ6Qlw5Cwfp). ::: Device policies support the following activities: - Retrieving all device policies, see [Retrieving all device policies](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving a specific device policy, see [Retrieving a specific device policy](docId\:aL8GMecutFpZ6Qlw5Cwfp) - Creating a device policy, see [Creating a device policy](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Editing a device policy, see [Editing a device policy](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Deleting a device policy, see [Deleting a device policy](docId\:aL8GMecutFpZ6Qlw5Cwfp). ## Retrieving all Device Policies To retrieve all *device-policy/groups* entities, use the REST API call below: - **Method:** GET /api/v1/policies/device-policies/device-policy/groups - **Resource:** Path If processed correctly, a JSON body containing a list of all *device-policy/groups* entities is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python GET /api/v1/policies/device-policies/device-policy/groups Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "items": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "description": "string", "is_default": true, "rules": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "description": "string", "type": "browser", "label": "high", "browser_config": { "user_agent": "string", "mode": "allow" }, "network_config": { "ip_address": "string", "netmask": "string", "mode": "allow" }, "hostchecker_config": { "name": "string", "type": "predefined", "predefined_rule": { "type": "antivirus", "hostchecker_level_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_product_list_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_level_name": "string", "hostchecker_product_list": { "windows": { "products": [ "string" ], "vendors": [ "string" ] }, "mac": { "products": [ "string" ], "vendors": [ "string" ] } }, "user_settings": { "hdd_encryption_settings": { "encrypt_drives": [ "string" ] } } }, "custom_rule": { "platform": "windows", "type": "process", "registry": { "root_key": "HKEY_LOCAL_MACHINE", "sub_key": "string", "type": "string", "key": "string", "value": "string", "is_64_bit": true, "remediate": true, "monitor": true }, "process": { "process_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "mobile_os_check": { "os_version": "string", "rule_separator": "above" }, "desktop_os_check": [ { "os_version": "string", "service_pack_version": "string" } ], "file": { "file_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "cve_check": { "check_all": true, "cve_list": [ "string" ] }, "mobile_jail_break_root_check_enabled": true, "netbios": { "allow": true, "names": [ "string" ] }, "mac_address": { "allow": true, "address": [ "string" ] } } }, "allow_delete": true, "is_default": true } ] } ] } ``` ## Retrieving a Specific Device Policy To retrieve a single *device-policy/groups* entity, use the REST API call below: - **Method:** GET /api/v1/policies/device-policies/device-policy/groups/ - **Resource:** Path If processed correctly, a JSON body containing the *device-policy/groups* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python GET /api/v1/policies/device-policies/device-policy/groups/{id} Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "description": "string", "is_default": true, "rules": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "description": "string", "type": "browser", "label": "high", "browser_config": { "user_agent": "string", "mode": "allow" }, "network_config": { "ip_address": "string", "netmask": "string", "mode": "allow" }, "hostchecker_config": { "name": "string", "type": "predefined", "predefined_rule": { "type": "antivirus", "hostchecker_level_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_product_list_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_level_name": "string", "hostchecker_product_list": { "windows": { "products": [ "string" ], "vendors": [ "string" ] }, "mac": { "products": [ "string" ], "vendors": [ "string" ] } }, "user_settings": { "hdd_encryption_settings": { "encrypt_drives": [ "string" ] } } }, "custom_rule": { "platform": "windows", "type": "process", "registry": { "root_key": "HKEY_LOCAL_MACHINE", "sub_key": "string", "type": "string", "key": "string", "value": "string", "is_64_bit": true, "remediate": true, "monitor": true }, "process": { "process_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "mobile_os_check": { "os_version": "string", "rule_separator": "above" }, "desktop_os_check": [ { "os_version": "string", "service_pack_version": "string" } ], "file": { "file_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "cve_check": { "check_all": true, "cve_list": [ "string" ] }, "mobile_jail_break_root_check_enabled": true, "netbios": { "allow": true, "names": [ "string" ] }, "mac_address": { "allow": true, "address": [ "string" ] } } }, "allow_delete": true, "is_default": true } ] } ``` ## Creating a Device Policy To create a *device-policy/groups* entity, use the REST API call below: - **Method:** POST /api/v1/policies/device-policies/device-policy/groups - **Resource:** Path - **JSON Data:** JSON dictionary representing a new *device-policy/groups* entity. If processed correctly, a JSON body containing the new *device-policy/groups* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/v1/policies/device-policies/device-policy/groups Authorization: Content-Type: application/json Request Body { "name": "string", "description": "string", "is_default": true, "rules": [ { "additionalProp1": {} } ], "rule_requirements": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "device_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "all_of_the_above": "string", "any_of_the_above": "string", "custom_expression_enabled": true, "custom_expression": "string", "platform": "windows" } ], "remediation": { "additionalProp1": {} }, "enable_custom_instructions": true, "custom_instructions": "string" } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "description": "string", "is_default": true, "rule_names": [ "string" ], "rules": [ { "additionalProp1": {} } ], "rule_requirements": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "device_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "all_of_the_above": "string", "any_of_the_above": "string", "custom_expression_enabled": true, "custom_expression": "string", "platform": "windows" } ], "remediation": { "additionalProp1": {} }, "enable_custom_instructions": true, "custom_instructions": "string" } ``` ## Editing a Device Policy To edit a *device-policy/groups* entity, use the REST API call below: - **Method:** PUT /api/v1/policies/device-policies/device-policy/groups/ - **Resource:** Path - **JSON Data:** JSON dictionary representing changed properties for a *device-policy/groups* entity. If processed correctly, a JSON body containing the updated *device-policy/groups* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python PUT /api/v1/policies/device-policies/device-policy/groups/{id} Authorization: Content-Type: application/json Request Body { "name": "string", "description": "string" } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "description": "string", "is_default": true, "rules": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "description": "string", "type": "browser", "label": "high", "browser_config": { "user_agent": "string", "mode": "allow" }, "network_config": { "ip_address": "string", "netmask": "string", "mode": "allow" }, "hostchecker_config": { "name": "string", "type": "predefined", "predefined_rule": { "type": "antivirus", "hostchecker_level_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_product_list_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_level_name": "string", "hostchecker_product_list": { "windows": { "products": [ "string" ], "vendors": [ "string" ] }, "mac": { "products": [ "string" ], "vendors": [ "string" ] } }, "user_settings": { "hdd_encryption_settings": { "encrypt_drives": [ "string" ] } } }, "custom_rule": { "platform": "windows", "type": "process", "registry": { "root_key": "HKEY_LOCAL_MACHINE", "sub_key": "string", "type": "string", "key": "string", "value": "string", "is_64_bit": true, "remediate": true, "monitor": true }, "process": { "process_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "mobile_os_check": { "os_version": "string", "rule_separator": "above" }, "desktop_os_check": [ { "os_version": "string", "service_pack_version": "string" } ], "file": { "file_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "cve_check": { "check_all": true, "cve_list": [ "string" ] }, "mobile_jail_break_root_check_enabled": true, "netbios": { "allow": true, "names": [ "string" ] }, "mac_address": { "allow": true, "address": [ "string" ] } } }, "allow_delete": true, "is_default": true } ] } ``` ## Deleting a Device Policy To delete a *device-policy/groups* entity, use the REST API call below: - **Method:** DELETE /api/v1/policies/device-policies/device-policy/groups/ - **Resource:** Path If processed correctly, a confirmation is returned. Otherwise, an error is returned. ### Request The following is an example request: ```python DELETE /api/v1/policies/device-policies/device-policy/groups/{id} Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 204 Device-policy/groups deleted successfully Content-Type: application/json ``` # Device Policy Rules (device-policy/rules) The *device-policy/rules* entity represents a *nZTA* policy rule configuration. Device policy rules support the following activities: - Retrieving all device policy rules, see [Retrieving all device policy rules](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving a specific device policy rule, see [Retrieving a specific device policy rule](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Creating a device policy rule, see [Creating a device policy rule](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Editing a device policy rule, see [Editing a device policy rule](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Deleting a device policy rule, see [Deleting a device policy rule](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Adding a device policy rule to a device policy, see [Adding a device policy rule to a device policy](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Removing a device policy rule from a device policy, see [Removing a device policy rule from a device policy](docId\:aL8GMecutFpZ6Qlw5Cwfp). :::hint{type="info" indent="1"} Device rules added or edited through the API are considered *custom* and do not use the "Security Level" field. This field applies only to built-in default device rules. ::: ## Retrieving all Device Policy Rules To retrieve all *device-policy/rules* entities, use the REST API call below: - **Method:** GET /api/v1/policies/device-policies/device-policy/rules - **Resource:** Path If processed correctly, a JSON body containing a list of all *device-policy/rules* entities is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python GET /api/v1/policies/device-policies/device-policy/rules Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "items": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "description": "string", "type": "browser", "label": "high", "browser_config": { "user_agent": "string", "mode": "allow" }, "network_config": { "ip_address": "string", "netmask": "string", "mode": "allow" }, "hostchecker_config": { "name": "string", "type": "predefined", "predefined_rule": { "type": "antivirus", "hostchecker_level_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_product_list_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_level_name": "string", "hostchecker_product_list": { "windows": { "products": [ "string" ], "vendors": [ "string" ] }, "mac": { "products": [ "string" ], "vendors": [ "string" ] } }, "user_settings": { "hdd_encryption_settings": { "encrypt_drives": [ "string" ] } } }, "custom_rule": { "platform": "windows", "type": "process", "registry": { "root_key": "HKEY_LOCAL_MACHINE", "sub_key": "string", "type": "string", "key": "string", "value": "string", "is_64_bit": true, "remediate": true, "monitor": true }, "process": { "process_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "mobile_os_check": { "os_version": "string", "rule_separator": "above" }, "desktop_os_check": [ { "os_version": "string", "service_pack_version": "string" } ], "file": { "file_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "cve_check": { "check_all": true, "cve_list": [ "string" ] }, "mobile_jail_break_root_check_enabled": true, "netbios": { "allow": true, "names": [ "string" ] }, "mac_address": { "allow": true, "address": [ "string" ] } } }, "allow_delete": true, "is_default": true } ] } ``` ## Retrieving a Specific Device Policy Rule To retrieve a single *device-policy/rules* entity, use the REST API call below: - **Method:** GET /api/v1/policies/device-policies/device-policy/rules/ - **Resource:** Path If processed correctly, a JSON body containing the *device-policy/rules* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python GET /api/v1/policies/device-policies/device-policy/rules/{id} Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "description": "string", "type": "browser", "label": "high", "browser_config": { "user_agent": "string", "mode": "allow" }, "network_config": { "ip_address": "string", "netmask": "string", "mode": "allow" }, "hostchecker_config": { "name": "string", "type": "predefined", "predefined_rule": { "type": "antivirus", "hostchecker_level_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_product_list_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_level_name": "string", "hostchecker_product_list": { "windows": { "products": [ "string" ], "vendors": [ "string" ] }, "mac": { "products": [ "string" ], "vendors": [ "string" ] } }, "user_settings": { "hdd_encryption_settings": { "encrypt_drives": [ "string" ] } } }, "custom_rule": { "platform": "windows", "type": "process", "registry": { "root_key": "HKEY_LOCAL_MACHINE", "sub_key": "string", "type": "string", "key": "string", "value": "string", "is_64_bit": true, "remediate": true, "monitor": true }, "process": { "process_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "mobile_os_check": { "os_version": "string", "rule_separator": "above" }, "desktop_os_check": [ { "os_version": "string", "service_pack_version": "string" } ], "file": { "file_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "cve_check": { "check_all": true, "cve_list": [ "string" ] }, "mobile_jail_break_root_check_enabled": true, "netbios": { "allow": true, "names": [ "string" ] }, "mac_address": { "allow": true, "address": [ "string" ] } } }, "allow_delete": true, "is_default": true } ``` ## Creating a Device Policy Rule You can create rules for the following rule types: - antispyware - cve\_check - firewall - hdd\_encryption - mac\_address - netbios - patch\_management - process - network - registry - file - antivirus - os - jail\_break\_root To create a *device-policy/rules* entity, use the REST API call below: - **Method:** POST /api/v1/policies/device-policies/device-policy/rules - **Resource:** Path - **JSON Data:** JSON dictionary representing a new *device-policy/rules* entity. If processed correctly, a JSON body containing the new *device-policy/rules* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/v1/policies/device-policies/device-policy/rules Authorization: Content-Type: application/json Request Body { "name": "string", "description": "string", "type": "browser", "label": "high", "browser_config": { "user_agent": "string", "mode": "allow" }, "network_config": { "ip_address": "string", "netmask": "string", "mode": "allow" }, "hostchecker_config": { "name": "string", "type": "predefined", "predefined_rule": { "type": "antivirus", "hostchecker_level_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_product_list_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "user_settings": { "hdd_encryption_settings": { "encrypt_drives": [ "string" ] } }, "hostchecker_level_name": "string", "hostchecker_product_list": { "products": [ "string" ], "vendors": [ "string" ] }, "platform": "windows" }, "custom_rule": { "platform": "windows", "type": "process", "registry": { "root_key": "HKEY_LOCAL_MACHINE", "sub_key": "string", "type": "string", "key": "string", "value": "string", "is_64_bit": true, "remediate": true, "monitor": true }, "process": { "process_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "mobile_os_check": { "os_version": "string", "rule_separator": "above" }, "desktop_os_check": [ { "os_version": "string", "service_pack_version": "string" } ], "file": { "file_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "cve_check": { "check_all": true, "cve_list": [ "string" ] }, "mobile_jail_break_root_check_enabled": true, "netbios": { "allow": true, "names": [ "string" ] }, "mac_address": { "allow": true, "address": [ "string" ] } } } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "description": "string", "type": "browser", "label": "high", "browser_config": { "user_agent": "string", "mode": "allow" }, "network_config": { "ip_address": "string", "netmask": "string", "mode": "allow" }, "hostchecker_config": { "name": "string", "type": "predefined", "predefined_rule": { "type": "antivirus", "hostchecker_level_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_product_list_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_level_name": "string", "hostchecker_product_list": { "windows": { "products": [ "string" ], "vendors": [ "string" ] }, "mac": { "products": [ "string" ], "vendors": [ "string" ] } }, "user_settings": { "hdd_encryption_settings": { "encrypt_drives": [ "string" ] } } }, "custom_rule": { "platform": "windows", "type": "process", "registry": { "root_key": "HKEY_LOCAL_MACHINE", "sub_key": "string", "type": "string", "key": "string", "value": "string", "is_64_bit": true, "remediate": true, "monitor": true }, "process": { "process_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "mobile_os_check": { "os_version": "string", "rule_separator": "above" }, "desktop_os_check": [ { "os_version": "string", "service_pack_version": "string" } ], "file": { "file_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "cve_check": { "check_all": true, "cve_list": [ "string" ] }, "mobile_jail_break_root_check_enabled": true, "netbios": { "allow": true, "names": [ "string" ] }, "mac_address": { "allow": true, "address": [ "string" ] } } }, "allow_delete": true, "is_default": true } ``` ## Editing a Device Policy Rule To edit a *device-policy/rules* entity, use the REST API call below: - **Method:** PUT /api/v1/policies/device-policies/device-policy/rules/ - **Resource:** Path - **JSON Data:** JSON dictionary representing changed properties for a *device-policy/rules* entity. If processed correctly, a JSON body containing the updated *device-policy/rules* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python PUT /api/v1/policies/device-policies/device-policy/rules/{id} Authorization: Content-Type: application/json Request Body { "name": "string", "description": "string", "type": "browser", "label": "high", "browser_config": { "user_agent": "string", "mode": "allow" }, "network_config": { "ip_address": "string", "netmask": "string", "mode": "allow" }, "hostchecker_config": { "name": "string", "type": "predefined", "predefined_rule": { "type": "antivirus", "hostchecker_level_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_product_list_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "user_settings": { "hdd_encryption_settings": { "encrypt_drives": [ "string" ] } }, "hostchecker_level_name": "string", "hostchecker_product_list": { "products": [ "string" ], "vendors": [ "string" ] }, "platform": "windows" }, "custom_rule": { "platform": "windows", "type": "process", "registry": { "root_key": "HKEY_LOCAL_MACHINE", "sub_key": "string", "type": "string", "key": "string", "value": "string", "is_64_bit": true, "remediate": true, "monitor": true }, "process": { "process_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "mobile_os_check": { "os_version": "string", "rule_separator": "above" }, "desktop_os_check": [ { "os_version": "string", "service_pack_version": "string" } ], "file": { "file_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "cve_check": { "check_all": true, "cve_list": [ "string" ] }, "mobile_jail_break_root_check_enabled": true, "netbios": { "allow": true, "names": [ "string" ] }, "mac_address": { "allow": true, "address": [ "string" ] } } } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "description": "string", "type": "browser", "label": "high", "browser_config": { "user_agent": "string", "mode": "allow" }, "network_config": { "ip_address": "string", "netmask": "string", "mode": "allow" }, "hostchecker_config": { "name": "string", "type": "predefined", "predefined_rule": { "type": "antivirus", "hostchecker_level_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_product_list_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "hostchecker_level_name": "string", "hostchecker_product_list": { "windows": { "products": [ "string" ], "vendors": [ "string" ] }, "mac": { "products": [ "string" ], "vendors": [ "string" ] } }, "user_settings": { "hdd_encryption_settings": { "encrypt_drives": [ "string" ] } } }, "custom_rule": { "platform": "windows", "type": "process", "registry": { "root_key": "HKEY_LOCAL_MACHINE", "sub_key": "string", "type": "string", "key": "string", "value": "string", "is_64_bit": true, "remediate": true, "monitor": true }, "process": { "process_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "mobile_os_check": { "os_version": "string", "rule_separator": "above" }, "desktop_os_check": [ { "os_version": "string", "service_pack_version": "string" } ], "file": { "file_name": "string", "md5_checksum": "string", "sha256_checksum": "string", "monitor": true, "action": "allow" }, "cve_check": { "check_all": true, "cve_list": [ "string" ] }, "mobile_jail_break_root_check_enabled": true, "netbios": { "allow": true, "names": [ "string" ] }, "mac_address": { "allow": true, "address": [ "string" ] } } }, "allow_delete": true, "is_default": true } ``` ## Deleting a Device Policy Rule To delete a *device-policy/rules* entity, use the REST API call below: - **Method:** DELETE /api/v1/policies/device-policies/device-policy/rules/ - **Resource:** Path If processed correctly, a confirmation is returned. Otherwise, an error is returned. ### Request The following is an example request: ```python DELETE /api/v1/policies/device-policies/device-policy/rules/{id} Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 204 Device-policy/rules deleted successfully Content-Type: application/json ``` ## Adding a Device Policy Rule to a Device Policy To add a *device-policy/rule* entity to a *device-policy/rule* entity, use the REST API call below: - **Method:** PUT /api/v1/policies/device-policies/groups//rules/ - **Resource:** Path If processed correctly, a confirmation is returned. Otherwise, an error is returned. ### Request The following is an example request: ```python PUT /api/v1/policies/device-policies/groups/{id}/rules/{rule_id} Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 204 Rule added to Device Policy successfully Content-Type: application/json ``` ## Removing a Device Policy Rule from a Device Policy To remove a *device-policy/rule* entity from a *device-policy/rule* entity, use the REST API call below: - **Method:** DELETE /api/v1/policies/device-policies/groups//rules/ - **Resource:** Path If processed correctly, a confirmation is returned. Otherwise, an error is returned. ### Request The following is an example request: ```bash DELETE /api/v1/policies/device-policies/groups/{id}/rules/{rule_id} Authorization:- Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 204 Rule in Device Policy Group deleted successfully Content-Type: application/json ``` # Gateway (gateways) The *gateways* entity represents a *ZTA Gateway*. Gateways support the following activities: - Retrieving all gateways, see [Retrieving all gateways](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Creating a gateway, see [Creating a gateway](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Editing a gateway, see [Editing a gateway](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Deleting a gateway, see [Deleting a gateway](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Renewing a client certificate, see [Renewing a client certificate](docId\:aL8GMecutFpZ6Qlw5Cwfp). ## Retrieving all Gateways To retrieve all *gateways* entities, use the REST API call below: - **Method:** GET /api/gateways - **Resource:** Path If processed correctly, a JSON body containing a list of all *gateways* entities is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python GET /api/gateways Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body [ { "id": "e274bf3ebe3841a88ade1630515624c6", "name": "string", "gateway_type": "pzt_gateway", "state": "unregistered", "created": "string", "updated": "string", "type": "string", "model": "string", "serial_number": "string", "appliance_version": "string", "sdp_mode": "pzt-gateway", "location": { "name": "string", "city_id": 0 }, "notification_channel_status": "online", "orchestration": { "type": "vsphere", "mode": "auto", "state": "waiting-to-create" }, "external_ip": "string", "external_fqdn": "string", "public_ip": "string", "public_ips": [ "xx.xx.xx.xx" ], "dns_cname": "string", "salient_task": { "id": "e274bf3ebe3841a88ade1630515624c6", "status": "pending", "type": "system.operations.appliance.task", "group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "created": "string", "completed": "string" }, "group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "is_ready": true, "actions": [ "upgrade" ], "auto_upgrade": true, "capabilities": [ "readiness" ] } ] ``` ## Creating a Gateway To create a *gateways* entity, use the REST API call below: - **Method:** POST /api/gateways - **Resource:** Path - **JSON Data:** JSON dictionary representing a new *gateways* entity. If processed correctly, a JSON body containing the new *gateways* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/gateways Authorization: Content-Type: application/json Request Body { "name": "test_gateway", "orchestration_type": "vsphere" } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "e274bf3ebe3841a88ade1630515624c6", "name": "test_gateway", "state": "unregistered", "sdp_mode": "gateway", "notification_channel_status": "offline", "orchestration": { "type": "vsphere", "mode": "manual" } } ``` ## Editing a Gateway To edit a *gateways* entity, use the REST API call below: - **Method:** PUT /api/gateways/ - **Resource:** Path - **JSON Data:** JSON dictionary representing changed properties for a *gateways* entity. If processed correctly, a JSON body containing the updated *gateways* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python PUT /api/gateways/{gateway_id} Authorization: Content-Type: application/json Request Body { "group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "e274bf3ebe3841a88ade1630515624c6", "name": "string", "state": "unregistered", "created": "string", "updated": "string", "type": "string", "model": "string", "serial_number": "string", "appliance_version": "string", "sdp_mode": "pzt-gateway", "location": { "name": "string", "city_id": 0 }, "notification_channel_status": "online", "orchestration": { "type": "vsphere", "mode": "auto", "state": "waiting-to-create" }, "external_ip": "string", "external_fqdn": "string", "public_ip": "string", "salient_task": { "id": "e274bf3ebe3841a88ade1630515624c6", "status": "pending", "type": "system.operations.appliance.task", "group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "created": "string", "completed": "string" }, "group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "is_ready": true, "actions": [ "upgrade" ], "auto_upgrade": true, "capabilities": [ "readiness" ] } ``` ## Deleting a Gateway To delete a *gateways* entity, use the REST API call below: - **Method:** DELETE /api/gateways/ - **Resource:** Path If processed correctly, a confirmation is returned. Otherwise, an error is returned. ### Request The following is an example request: ```python DELETE /api/gateways/{gateway_id} Authorization: Content-Type: application/json Request Body { "id": "e274bf3ebe3841a88ade1630515624c6", } ``` ### Response The following is an example response: ```python HTTP/1.1 204 Gateway deleted successfully Content-Type: application/json ``` ## Renewing a Client Certificate To renew a certificate for a client, use the REST API call below: - **Method:** POST /api/gateways/self/certificates/client - **Resource:** Path - **JSON Data:** JSON dictionary representing a certificate signing request (CSR). If processed correctly, a JSON body containing the new client certificate is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/gateways/self/certificates/client Authorization: Content-Type: application/json Request Body { "csr": "string" } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "certificate": "string", "format": "PEM" } ``` # Gateway Settings Gateway settings are additional properties for a *ZTA Gateway*. Gateway settings support the following activities: - Retrieving the settings for a gateway, see [Retrieving the Settings for a Gateway](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Editing the settings for a gateway, see [Editing Settings for a Gateway](docId\:aL8GMecutFpZ6Qlw5Cwfp). ## Retrieving the Settings for a Gateway To retrieve the settings for a *gateways* entity, use the REST API call below: - **Method:** GET /api/gateways//settings/current - **Resource:** Path If processed correctly, a JSON body containing the properties for the *gateways* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python GET /api/gateways/{gateway_id}/settings/current Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "version": "string", "primary_dns": "string", "secondary_dns": "string", "dns_search_domain": "string", "internal_ip_address": "string", "internal_subnet": "string", "internal_gateway": "string", "external_ip_address": "string", "external_subnet": "string", "external_gateway": "string", "management_ip_address": "string", "management_subnet": "string", "management_gateway": "string", "connect_via_mgmt_interface": true, "model": "string", "rollback_version": "string", "use_dhcp": true, "previous_version": "string", "updated": "string", "public_ip_address": "string", "public_ip_addresses": [ "10.1.2.3" ], "dns_cname": "string" } ``` ## Editing Settings for a Gateway To edit the settings for a *gateways* entity, use the REST API call below: - **Method:** PUT /api/gateways/self/settings/current - **Resource:** Path - **JSON Data:** JSON dictionary representing updated settings If processed correctly, a JSON body containing the updated properties for the *gateways* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python PUT /api/gateways/self/settings/current Authorization: Content-Type: application/json Request Body { "version": "string", "primary_dns": "string", "secondary_dns": "string", "dns_search_domain": "string", "internal_ip_address": "string", "internal_subnet": "string", "internal_gateway": "string", "external_ip_address": "string", "external_subnet": "string", "external_gateway": "string", "management_ip_address": "string", "management_subnet": "string", "management_gateway": "string", "connect_via_mgmt_interface": true, "model": "string", "rollback_version": "string" } ``` ### Response The following is an example response: ```python HTTP/1.1 204 Gateway settings updated successfully Content-Type: application/json ``` # Gateway Groups (groups) The groups entity represents a *ZTA Gateway* group. Gateway groups support the following activities: - Retrieving a gateway groups, see [Retrieving a gateway groups](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Creating a gateway group, see [Creating a gateway group](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Editing a gateway group, see [Editing a gateway group](docId\:aL8GMecutFpZ6Qlw5Cwfp). ## Retrieving a Gateway Group To retrieve all gateway groups, use the REST API call below: - **Method:** GET /api/gateways/groups - **Resource:** Path If processed correctly, a JSON body containing a list of all gateway groups is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python GET /api/gateways/groups Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "items": [ { "name": "asia-pacific-grp", "description": "Gateway group assigned to Asia Pacific region", "load_balancer_ips": [ "10.1.2.3" ], "dns_cname": "string", "id": "e274bf3ebe3841a88ade1630515624c6", "external_fqdn": "string", "created": "string", "updated": "string", "members": [ "e274bf3ebe3841a88ade1630515624c6" ], "connected_members": [ "e274bf3ebe3841a88ade1630515624c6" ], "ready_members": [ "e274bf3ebe3841a88ade1630515624c6" ] } ], "total": 10 } ``` ## Creating a Gateway Group To create a gateway group, use the REST API call below: - **Method:** POST /api/gateways/groups - **Resource:** Path - **JSON Data:** JSON dictionary representing a new gateway group. If processed correctly, a JSON body containing the new gateway group is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/gateways/groups Authorization: Content-Type: application/json Request Body { "name": "asia-pacific-grp", "description": "Gateway group assigned to Asia Pacific region", "load_balancer_ips": [ "10.1.2.3" ], "dns_cname": "string", "members": [ "e274bf3ebe3841a88ade1630515624c6" ] } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "name": "asia-pacific-grp", "description": "Gateway group assigned to Asia Pacific region", "load_balancer_ips": [ "10.1.2.3" ], "dns_cname": "string", "id": "e274bf3ebe3841a88ade1630515624c6", "external_fqdn": "string", "created": "string", "updated": "string", "members": [ "e274bf3ebe3841a88ade1630515624c6" ], "connected_members": [ "e274bf3ebe3841a88ade1630515624c6" ], "ready_members": [ "e274bf3ebe3841a88ade1630515624c6" ] } ``` ## Editing a Gateway Group To edit a gateway group, use the REST API call below: - **Method:** PUT /api/gateways/groups/ - **Resource:** Path - **JSON Data:** JSON dictionary representing changed properties for a gateway group. If processed correctly, a JSON body containing the updated gateway group is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python PUT /api/gateways/groups/{id} Authorization: Content-Type: application/json Request Body { "name": "asia-pacific-grp", "description": "Gateway group assigned to Asia Pacific region", "load_balancer_ips": [ "10.1.2.3" ], "dns_cname": "string" } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "name": "asia-pacific-grp", "description": "Gateway group assigned to Asia Pacific region", "load_balancer_ips": [ "10.1.2.3" ], "dns_cname": "string", "id": "e274bf3ebe3841a88ade1630515624c6", "external_fqdn": "string", "created": "string", "updated": "string", "members": [ "e274bf3ebe3841a88ade1630515624c6" ], "connected_members": [ "e274bf3ebe3841a88ade1630515624c6" ], "ready_members": [ "e274bf3ebe3841a88ade1630515624c6" ] } ``` # Hostchecker Levels (hostchecker/levels) The *hostchecker/levels* entity represents a *nZTA* hostchecker configuration. :::hint{type="info" indent="1"} Hostchecker levels must be created and configured before device policies can be created successfully. ::: Hostchecker levels support the following activities: - Retrieving all hostchecker levels, see [Retrieving all hostchecker levels](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving a specific hostchecker level, see [Retrieving a specific hostchecker leve](docId\:aL8GMecutFpZ6Qlw5Cwfp)l. - Creating a hostchecker level, see [Creating a hostchecker level](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Editing a hostchecker level, see [Editing a hostchecker level](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Deleting a hostchecker level, see [Deleting a hostchecker level](docId\:aL8GMecutFpZ6Qlw5Cwfp). ## Retrieving all Hostchecker Levels To retrieve all *hostchecker/levels* entities, use the REST API call below: - **Method:** GET /api/v1/policies/device-policies/hostchecker/levels - **Resource:** Path If processed correctly, a JSON body containing a list of all *hostchecker/levels* entities is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```bash GET /api/v1/policies/device-policies/hostchecker/levels Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "items": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "antivirus": { "check_last_scan": true, "last_scan_period": 0, "check_definition": true, "definition_check_type": "days", "remediate_last_scan": true, "remediate_download_signatures": true, "monitor": true }, "firewall": { "remediate": true, "monitor": true }, "hdd_encryption": { "encrypt_all_drives": true, "pass_no_drive_detected": true }, "antispyware": { "monitor": true }, "patch_management": { "severity": { "critical": true, "important": true, "moderate": true, "low": true, "unspecified": true }, "category": { "security": true, "rollup": true, "critical": true, "regular": true, "driver": true, "service_pack": true, "unknown": true } } } ], "total": 0 } ``` ## Retrieving a Specific Hostchecker Level To retrieve a single *hostchecker/levels* entity, use the REST API call below: - **Method:** GET /api/v1/policies/device-policies/hostchecker/levels/ - **Resource:** Path If processed correctly, a JSON body containing the *hostchecker/levels* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python GET /api/v1/policies/device-policies/hostchecker/levels/{id} Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "antivirus": { "check_last_scan": true, "last_scan_period": 0, "check_definition": true, "definition_check_type": "days", "remediate_last_scan": true, "remediate_download_signatures": true, "monitor": true }, "firewall": { "remediate": true, "monitor": true }, "hdd_encryption": { "encrypt_all_drives": true, "pass_no_drive_detected": true }, "antispyware": { "monitor": true }, "patch_management": { "severity": { "critical": true, "important": true, "moderate": true, "low": true, "unspecified": true }, "category": { "security": true, "rollup": true, "critical": true, "regular": true, "driver": true, "service_pack": true, "unknown": true } } } ``` ## Creating a Hostchecker Level To create a *hostchecker/levels* entity, use the REST API call below: - **Method:** POST /api/v1/policies/device-policies/hostchecker/levels - **Resource:** Path - **JSON Data:** JSON dictionary representing a new *hostchecker/levels* entity. If processed correctly, a JSON body containing the new *hostchecker/levels* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/v1/policies/device-policies/hostchecker/levels Authorization: Content-Type: application/json Request Body { "name": "string", "antivirus": { "check_last_scan": true, "last_scan_period": 0, "check_definition": true, "definition_check_type": "days", "remediate_last_scan": true, "remediate_download_signatures": true, "monitor": true }, "firewall": { "remediate": true, "monitor": true }, "hdd_encryption": { "encrypt_all_drives": true, "pass_no_drive_detected": true }, "antispyware": { "monitor": true }, "patch_management": { "severity": { "critical": true, "important": true, "moderate": true, "low": true, "unspecified": true }, "category": { "security": true, "rollup": true, "critical": true, "regular": true, "driver": true, "service_pack": true, "unknown": true } } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "antivirus": { "check_last_scan": true, "last_scan_period": 0, "check_definition": true, "definition_check_type": "days", "remediate_last_scan": true, "remediate_download_signatures": true, "monitor": true }, "firewall": { "remediate": true, "monitor": true }, "hdd_encryption": { "encrypt_all_drives": true, "pass_no_drive_detected": true }, "antispyware": { "monitor": true }, "patch_management": { "severity": { "critical": true, "important": true, "moderate": true, "low": true, "unspecified": true }, "category": { "security": true, "rollup": true, "critical": true, "regular": true, "driver": true, "service_pack": true, "unknown": true } } } ``` ## Editing a Hostchecker Level To edit a *hostchecker/levels* entity, use the REST API call below: - **Method:** PUT /api/v1/policies/device-policies/hostchecker/levels/ - **Resource:** Path - **JSON Data:** JSON dictionary representing changed properties for a *hostchecker/levels* entity. If processed correctly, a JSON body containing the updated *hostchecker/levels* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python PUT /api/v1/policies/device-policies/hostchecker/levels/{id} Authorization: Content-Type: application/json Request Body { "name": "string", "antivirus": { "check_last_scan": true, "last_scan_period": 0, "check_definition": true, "definition_check_type": "days", "remediate_last_scan": true, "remediate_download_signatures": true, "monitor": true }, "firewall": { "remediate": true, "monitor": true }, "hdd_encryption": { "encrypt_all_drives": true, "pass_no_drive_detected": true }, "antispyware": { "monitor": true }, "patch_management": { "severity": { "critical": true, "important": true, "moderate": true, "low": true, "unspecified": true }, "category": { "security": true, "rollup": true, "critical": true, "regular": true, "driver": true, "service_pack": true, "unknown": true } } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "antivirus": { "check_last_scan": true, "last_scan_period": 0, "check_definition": true, "definition_check_type": "days", "remediate_last_scan": true, "remediate_download_signatures": true, "monitor": true }, "firewall": { "remediate": true, "monitor": true }, "hdd_encryption": { "encrypt_all_drives": true, "pass_no_drive_detected": true }, "antispyware": { "monitor": true }, "patch_management": { "severity": { "critical": true, "important": true, "moderate": true, "low": true, "unspecified": true }, "category": { "security": true, "rollup": true, "critical": true, "regular": true, "driver": true, "service_pack": true, "unknown": true } } } ``` ## Deleting a Hostchecker Level To delete a *hostchecker/levels* entity, use the REST API call below: - **Method:** DELETE /api/v1/policies/device-policies/hostchecker/levels/ - **Resource:** Path If processed correctly, a confirmation is returned. Otherwise, an error is returned. ### Request The following is an example request: ```bash DELETE /api/v1/policies/device-policies/hostchecker/levels/{id} Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```bash HTTP/1.1 204 Hostchecker/levels deleted successfully Content-Type: application/json ``` # Hostchecker Products (hostchecker/products) The *hostchecker/products* entity represents a *nZTA* hostchecker configuration. Hostchecker products support the following activities: - Retrieving all hostchecker products, see [Retrieving all hostchecker products](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving a specific hostchecker product, see [Retrieving a specific hostchecker product](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Creating a hostchecker product, see [Creating a hostchecker product](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Editing a hostchecker product, see [Editing a hostchecker product](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Deleting a hostchecker product, see [Deleting a hostchecker product](docId\:aL8GMecutFpZ6Qlw5Cwfp). ## Retrieving all Hostchecker Products To retrieve all *hostchecker/products* entities, use the REST API call below: - **Method:** GET /api/v1/policies/device-policies/hostchecker/products - **Resource:** Path If processed correctly, a JSON body containing a list of all *hostchecker/products* entities is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python GET /api/v1/policies/device-policies/hostchecker/products Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "items": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "windows": { "antivirus": { "vendors": [ "string" ], "products": [ "string" ] }, "firewall": { "vendors": [ "string" ], "products": [ "string" ] }, "antispyware": { "vendors": [ "string" ], "products": [ "string" ] }, "hdd_encryption": { "vendors": [ "string" ], "products": [ "string" ] }, "patch_management": { "vendors": [ "string" ], "products": [ "string" ] } }, "mac": { "antivirus": { "vendors": [ "string" ], "products": [ "string" ] }, "firewall": { "vendors": [ "string" ], "products": [ "string" ] }, "antispyware": { "vendors": [ "string" ], "products": [ "string" ] }, "hdd_encryption": { "vendors": [ "string" ], "products": [ "string" ] }, "patch_management": { "vendors": [ "string" ], "products": [ "string" ] } } } ], "total": 0 } ``` ## Retrieving a Specific Hostchecker Product To retrieve a single *hostchecker/products* entity, use the REST API call below: - **Method:** GET /api/v1/policies/device-policies/hostchecker/products/ - **Resource:** Path If processed correctly, a JSON body containing the *hostchecker/products* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```bash GET /api/v1/policies/device-policies/hostchecker/products/{id} Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "windows": { "antivirus": { "vendors": [ "string" ], "products": [ "string" ] }, "firewall": { "vendors": [ "string" ], "products": [ "string" ] }, "antispyware": { "vendors": [ "string" ], "products": [ "string" ] }, "hdd_encryption": { "vendors": [ "string" ], "products": [ "string" ] }, "patch_management": { "vendors": [ "string" ], "products": [ "string" ] } }, "mac": { "antivirus": { "vendors": [ "string" ], "products": [ "string" ] }, "firewall": { "vendors": [ "string" ], "products": [ "string" ] }, "antispyware": { "vendors": [ "string" ], "products": [ "string" ] }, "hdd_encryption": { "vendors": [ "string" ], "products": [ "string" ] }, "patch_management": { "vendors": [ "string" ], "products": [ "string" ] } } } ``` ## Creating a Hostchecker Product To create a *hostchecker/products* entity, use the REST API call below: - **Method:** POST /api/v1/policies/device-policies/hostchecker/products - **Resource:** Path - **JSON Data:** JSON dictionary representing a new *hostchecker/products* entity. If processed correctly, a JSON body containing the new *hostchecker/products* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/v1/policies/device-policies/hostchecker/products Authorization: Content-Type: application/json Request Body { "name": "string", "windows": { "antivirus": { "vendors": [ "string" ], "products": [ "string" ] }, "firewall": { "vendors": [ "string" ], "products": [ "string" ] }, "antispyware": { "vendors": [ "string" ], "products": [ "string" ] }, "hdd_encryption": { "vendors": [ "string" ], "products": [ "string" ] }, "patch_management": { "vendors": [ "string" ], "products": [ "string" ] } }, "mac": { "antivirus": { "vendors": [ "string" ], "products": [ "string" ] }, "firewall": { "vendors": [ "string" ], "products": [ "string" ] }, "antispyware": { "vendors": [ "string" ], "products": [ "string" ] }, "hdd_encryption": { "vendors": [ "string" ], "products": [ "string" ] }, "patch_management": { "vendors": [ "string" ], "products": [ "string" ] } } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "windows": { "antivirus": { "vendors": [ "string" ], "products": [ "string" ] }, "firewall": { "vendors": [ "string" ], "products": [ "string" ] }, "antispyware": { "vendors": [ "string" ], "products": [ "string" ] }, "hdd_encryption": { "vendors": [ "string" ], "products": [ "string" ] }, "patch_management": { "vendors": [ "string" ], "products": [ "string" ] } }, "mac": { "antivirus": { "vendors": [ "string" ], "products": [ "string" ] }, "firewall": { "vendors": [ "string" ], "products": [ "string" ] }, "antispyware": { "vendors": [ "string" ], "products": [ "string" ] }, "hdd_encryption": { "vendors": [ "string" ], "products": [ "string" ] }, "patch_management": { "vendors": [ "string" ], "products": [ "string" ] } } } ``` ## Editing a Hostchecker Product To edit a *hostchecker/products* entity, use the REST API call below: - **Method:** PUT /api/v1/policies/device-policies/hostchecker/products/ - **Resource:** Path - **JSON Data:** JSON dictionary representing changed properties for a *hostchecker/products* entity. If processed correctly, a JSON body containing the updated *hostchecker/products* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python PUT /api/v1/policies/device-policies/hostchecker/products/{id} Authorization: Content-Type: application/json Request Body { "name": "string", "windows": { "antivirus": { "vendors": [ "string" ], "products": [ "string" ] }, "firewall": { "vendors": [ "string" ], "products": [ "string" ] }, "antispyware": { "vendors": [ "string" ], "products": [ "string" ] }, "hdd_encryption": { "vendors": [ "string" ], "products": [ "string" ] }, "patch_management": { "vendors": [ "string" ], "products": [ "string" ] } }, "mac": { "antivirus": { "vendors": [ "string" ], "products": [ "string" ] }, "firewall": { "vendors": [ "string" ], "products": [ "string" ] }, "antispyware": { "vendors": [ "string" ], "products": [ "string" ] }, "hdd_encryption": { "vendors": [ "string" ], "products": [ "string" ] }, "patch_management": { "vendors": [ "string" ], "products": [ "string" ] } } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "windows": { "antivirus": { "vendors": [ "string" ], "products": [ "string" ] }, "firewall": { "vendors": [ "string" ], "products": [ "string" ] }, "antispyware": { "vendors": [ "string" ], "products": [ "string" ] }, "hdd_encryption": { "vendors": [ "string" ], "products": [ "string" ] }, "patch_management": { "vendors": [ "string" ], "products": [ "string" ] } }, "mac": { "antivirus": { "vendors": [ "string" ], "products": [ "string" ] }, "firewall": { "vendors": [ "string" ], "products": [ "string" ] }, "antispyware": { "vendors": [ "string" ], "products": [ "string" ] }, "hdd_encryption": { "vendors": [ "string" ], "products": [ "string" ] }, "patch_management": { "vendors": [ "string" ], "products": [ "string" ] } } } ``` ## Deleting a Hostchecker Product To delete a *hostchecker/products* entity, use the REST API call below: - **Method:** DELETE /api/v1/policies/device-policies/hostchecker/products/ - **Resource:** Path If processed correctly, a confirmation is returned. Otherwise, an error is returned. ### Request The following is an example request: ```python DELETE /api/v1/policies/device-policies/hostchecker/products/{id} Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 204 Hostchecker/products deleted successfully Content-Type: application/json ``` ```bash ``` # Resource Group (resource-groups) The resource-groups entity represents a *nZTA* group of resources (both sign-in resources and applications). Resource groups support the following activities: - Retrieving all resource groups, see [Retrieving All Resource Groups](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Creating a resource group, see [Creating a Resource Group](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Editing a resource group, see [Editing a Resource Group](docId\:aL8GMecutFpZ6Qlw5Cwfp). ## Retrieving All Resource Groups To retrieve a resource\_groups entity, use the REST API call below: - **Method:** GET /api/v1/policies/resource-groups - **Resource:** Path If processed correctly, a JSON body containing a list of all resource-groups entities is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```bash GET /api/v1/policies/resource-groups Authorization:Content-Type: application/json ``` ### Response The following is an example response: ```python { "items": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "sign_in", "resources": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "sign_in", "description": "string", "sign_in_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "policy_type": "admin", "url_pattern": "string", "realm": "string", "primary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "secondary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "primary_authorization_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "app_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "access_type": "application", "resource_type": "fqdn", "resource": "string", "bookmark_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "web", "description": "string", "launch_window": true, "url": "string", "icon": "string" }, "saml_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sp_metadata": "string" } } ] } ] } ``` ## Creating a Resource Group To create a resource\_group entity, use the REST API call below: - **Method:** POST /api/v1/policies/resource-groups - **Resource:** Path - **JSON Data:** JSON dictionary representing a new resource-groups entity. If processed correctly, a JSON body containing the new resource-groups is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/v1/policies/resource-groups Authorization: Content-Type: application/json Request Body { "name": "string", "type": "string", "resources": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "sign_in", "description": "string", "sign_in_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "policy_type": "admin", "url_pattern": "string", "realm": "string", "primary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "secondary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "primary_authorization_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "app_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "access_type": "application", "resource_type": "fqdn", "resource": "string", "bookmark_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "web", "description": "string", "launch_window": true, "url": "string", "icon": "string" }, "saml_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sp_metadata": "string" } } } ] } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "sign_in", "resources": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "sign_in", "description": "string", "sign_in_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "policy_type": "admin", "url_pattern": "string", "realm": "string", "primary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "secondary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "primary_authorization_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "app_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "access_type": "application", "resource_type": "fqdn", "resource": "string", "bookmark_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "web", "description": "string", "launch_window": true, "url": "string", "icon": "string" }, "saml_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sp_metadata": "string" } } } ] } ``` ## Editing a Resource Group To edit a resource-group entity, use the REST API call below: - **Method:** PUT /api/v1/policies/resource-groups/\ - **Resource:** Path - **JSON Data:** JSON dictionary representing changed properties for a resource-groups entity. If processed correctly, a JSON body containing the updated resources-group entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python PUT /api/v1/policies/resource-groups/{id} Authorization: Content-Type: application/json Request Body { "name": "string", "type": "string", "resources": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "sign_in", "description": "string", "sign_in_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "policy_type": "admin", "url_pattern": "string", "realm": "string", "primary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "secondary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "primary_authorization_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "app_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "access_type": "application", "resource_type": "fqdn", "resource": "string", "bookmark_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "web", "description": "string", "launch_window": true, "url": "string", "icon": "string" }, "saml_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sp_metadata": "string" } } } ] } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "sign_in", "resources": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "sign_in", "description": "string", "sign_in_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "policy_type": "admin", "url_pattern": "string", "realm": "string", "primary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "secondary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "primary_authorization_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "app_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "access_type": "application", "resource_type": "fqdn", "resource": "string", "bookmark_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "web", "description": "string", "launch_window": true, "url": "string", "icon": "string" }, "saml_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sp_metadata": "string" } } } ] } ``` # Role Mapping Rules (role-mapping-rules) The *role-mapping-rules* entity represents a *nZTA* role mapping rule. Role mapping rules support the following activities: - Retrieving role map rules, see [Retrieving All Role Mapping Rules](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Creating a role mapping rule, see [Creating a Role Mapping Rule](docId\:aL8GMecutFpZ6Qlw5Cwfp). ## Retrieving All Role Mapping Rules To retrieve a list of all *role-mapping-rules* entities, use the REST API call below: - **Method:** GET /api/v1/policies/role-mapping-rules - **Resource:** Path If processed correctly, a JSON body containing a list of all *role-mapping-rules* entities is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```bash GET /api/v1/policies/role-mapping-rules Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "items": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "username", "name": "string", "attribute": "string", "value": "string" } ] } ``` ## Creating a Role Mapping Rule To create a *role-mapping-rules* entity, use the REST API call below: - **Method:** POST /api/v1/policies/role-mapping-rules - **Resource:** Path - **JSON Data:** JSON dictionary representing a new *role-mapping-rules* entity. If processed correctly, a JSON body containing the new *role-mapping-rules* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/v1/policies/role-mapping-rules Authorization: Content-Type: application/json Request Body { "type": "username", "name": "string", "attribute": "string", "value": "string" } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "username", "name": "string", "attribute": "string", "value": "string" } ``` # Secure Access Policy (secure-access-policies) The *secure-access-policies* entity represents a *nZTA* secure access policy. Secure access policies support the following activities: - Retrieving All Secure Access Policies, see [Retrieving All Secure Access Policies](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Creating a Secure Access Policy, see [Creating a Secure Access Policy](docId\:aL8GMecutFpZ6Qlw5Cwfp). ## Retrieving All Secure Access Policies To retrieve all *secure-access-policies* entities, use the REST API call below: - **Method:** GET /api/v1/policies/secure-access-policies - **Resource:** Path If processed correctly, a JSON body containing a list of all *secure-access-policies* entities is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python GET /api/v1/policies/secure-access-policies Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "items": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "sign_in", "resource_type": "single", "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "resource_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "device_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "gateway_type": "single", "gateway_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "gateway_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "user_rule_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "resource_config": { "name": "string" }, "resource_group_config": { "name": "string" }, "device_policy_config": { "name": "string" }, "user_rule_group_config": { "name": "string", "role_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "admin", "name": "string", "redirect_url": "string" } } } ] } ``` ## Creating a Secure Access Policy To create a *secure-access-policies* entity, use the REST API call below: - **Method:** POST /api/v1/policies/secure-access-policies - **Resource:** Path - **JSON Data:** JSON dictionary representing a new secure-access-policies entity. If processed correctly, a JSON body containing the new secure-access-policies entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/v1/policies/secure-access-policies Authorization: Content-Type: application/json Request Body { "type": "sign_in", "resource_type": "single", "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "resource_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "device_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "gateway_type": "single", "gateway_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "gateway_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "user_rule_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "sign_in", "resource_type": "single", "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "resource_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "device_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "gateway_type": "single", "gateway_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "gateway_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "user_rule_group_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "resource_config": { "name": "string" }, "resource_group_config": { "name": "string" }, "device_policy_config": { "name": "string" }, "user_rule_group_config": { "name": "string", "role_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "admin", "name": "string", "redirect_url": "string" } } } ``` # Enterprise Integrations Configurations Service (integrations/syslog) The *integrations/syslog* entity holds information about third party Enterprise Integrations Syslog Server configurations. This entity support the following activities: - Retrieving the Enterprise Integrations Syslog forwarding configuration details, grouped by log type, see [Retrieving the Enterprise Integrations Syslog Forwarding Configuration](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Creating an Enterprise Integrations Syslog forwarding configuration, see [Adding Enterprise Integrations Syslog Forwarding Configuration Details](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving a List of Enterprise Integrations Syslog forwarding configurations, see [Retrieving a List of Enterprise Integrations Syslog Configurations](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving a specific Enterprise Integrations Syslog forwarding configuration, see [Retrieving a Specific Enterprise Integrations Syslog Configuration](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Editing an Enterprise Integrations Syslog forwarding configuration, see [Editing an Enterprise Integrations Syslog Configuration](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Removing an Enterprise Integrations Syslog forwarding configuration, see [Removing an Enterprise Integrations Syslog Configuration](docId\:aL8GMecutFpZ6Qlw5Cwfp). ## Retrieving the Enterprise Integrations Syslog Forwarding Configuration To retrieve an *integrations/syslog* entity, use the REST API call below: - **Method:** GET /api/integrations/syslog - **Resource:** Path If processed correctly, a JSON body is returned that contains a list of syslog servers categorized by log type (access, event, admin). Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python GET /api/integrations/syslog Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "access": [ { "name": "string", "server": "string", "log_types": [ "access" ], "facility": "LOCAL0", "protocol": "TLS", "certificate_id": "3fa85f6457174562b3fc2c963f66afa6", "filter_id": "123e4567e89b12d3a456426614174000", "gateway_ids": [ "123e4567e89b12d3a456wr6614175643" ], "proxy_gateway_id": "123e4567e89b12d3a456wr6614175643", "id": "824411c22bf94e719ea757f8f3fd818e", "filter_name": "string", "created": "2021-01-27T00:00:00+00:00", "updated": "2021-01-27T00:00:00+00:00" } ], "admin": [ { "name": "string", "server": "string", "log_types": [ "access" ], "facility": "LOCAL0", "protocol": "TLS", "certificate_id": "3fa85f6457174562b3fc2c963f66afa6", "filter_id": "123e4567e89b12d3a456426614174000", "gateway_ids": [ "123e4567e89b12d3a456wr6614175643" ], "proxy_gateway_id": "123e4567e89b12d3a456wr6614175643", "id": "824411c22bf94e719ea757f8f3fd818e", "filter_name": "string", "created": "2021-01-27T00:00:00+00:00", "updated": "2021-01-27T00:00:00+00:00" } ], "events": [ { "name": "string", "server": "string", "log_types": [ "access" ], "facility": "LOCAL0", "protocol": "TLS", "certificate_id": "3fa85f6457174562b3fc2c963f66afa6", "filter_id": "123e4567e89b12d3a456426614174000", "gateway_ids": [ "123e4567e89b12d3a456wr6614175643" ], "proxy_gateway_id": "123e4567e89b12d3a456wr6614175643", "id": "824411c22bf94e719ea757f8f3fd818e", "filter_name": "string", "created": "2021-01-27T00:00:00+00:00", "updated": "2021-01-27T00:00:00+00:00" } ] } ``` ## Adding Enterprise Integrations Syslog Forwarding Configuration Details To add an *integrations/syslog* entity containing a syslog forwarding configuration, use the REST API call below: - **Method:** POST /api/integrations/syslog - **Resource:** Path - **JSON Data:** JSON dictionary representing a new integrations/syslog entity. If processed correctly, a JSON body containing the new integrations/syslog entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/integrations/syslog Authorization: Content-Type: application/json Request Body { "name": "string", "server": "string", "log_types": [ "access" ], "facility": "LOCAL0", "protocol": "TLS", "certificate_id": "3fa85f6457174562b3fc2c963f66afa6", "filter_id": "123e4567e89b12d3a456426614174000", "gateway_ids": [ "123e4567e89b12d3a456wr6614175643" ], "proxy_gateway_id": "123e4567e89b12d3a456wr6614175643" } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "name": "string", "server": "string", "log_types": [ "access" ], "facility": "LOCAL0", "protocol": "TLS", "certificate_id": "3fa85f6457174562b3fc2c963f66afa6", "filter_id": "123e4567e89b12d3a456426614174000", "gateway_ids": [ "123e4567e89b12d3a456wr6614175643" ], "proxy_gateway_id": "123e4567e89b12d3a456wr6614175643", "id": "824411c22bf94e719ea757f8f3fd818e", "filter_name": "string", "created": "2021-01-27T00:00:00+00:00", "updated": "2021-01-27T00:00:00+00:00" } ``` ## Retrieving a List of Enterprise Integrations Syslog Configurations To retrieve a list of Enterprise Integrations Syslog Server configurations, use the REST API call below: - **Method:** GET /api/integrations/syslog/ui - **Resource:** Path If processed correctly, a JSON body containing a list of all *integrations/syslog/ui* entities is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python GET /api/integrations/syslog/ui Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "total": 0, "items": [ { "name": "string", "server": "string", "log_types": [ "access" ], "facility": "LOCAL0", "protocol": "TLS", "certificate_id": "3fa85f6457174562b3fc2c963f66afa6", "filter_id": "123e4567e89b12d3a456426614174000", "gateway_ids": [ "123e4567e89b12d3a456wr6614175643" ], "proxy_gateway_id": "123e4567e89b12d3a456wr6614175643", "id": "824411c22bf94e719ea757f8f3fd818e", "filter_name": "string", "created": "2021-01-27T00:00:00+00:00", "updated": "2021-01-27T00:00:00+00:00" } ] } ``` ## Retrieving a Specific Enterprise Integrations Syslog Configuration To retrieve a single *integrations/syslog* entity, use the REST API call below: - **Method:** GET /api/integrations/syslog/ - **Resource:** Path If processed correctly, a JSON body containing the *integrations/syslog* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```bash GET /api/integrations/syslog/{syslog_id} Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "name": "string", "server": "string", "log_types": [ "access" ], "facility": "LOCAL0", "protocol": "TLS", "certificate_id": "3fa85f6457174562b3fc2c963f66afa6", "filter_id": "123e4567e89b12d3a456426614174000", "gateway_ids": [ "123e4567e89b12d3a456wr6614175643" ], "proxy_gateway_id": "123e4567e89b12d3a456wr6614175643", "id": "824411c22bf94e719ea757f8f3fd818e", "filter_name": "string", "created": "2021-01-27T00:00:00+00:00", "updated": "2021-01-27T00:00:00+00:00" } ``` ## Editing an Enterprise Integrations Syslog Configuration To edit an *integrations/syslog* entity, use the REST API call below: - **Method:** PUT /api/integrations/syslog/ - **Resource:** Path - **JSON Data:** JSON dictionary representing changed properties for a *integrations/syslog* entity. If processed correctly, a JSON body containing the updated *integrations/syslog* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python PUT /api/integrations/syslog/{syslog_id} Authorization: Content-Type: application/json Request Body { "name": "string", "server": "string", "log_types": [ "access" ], "facility": "LOCAL0", "protocol": "TLS", "certificate_id": "3fa85f6457174562b3fc2c963f66afa6", "filter_id": "123e4567e89b12d3a456426614174000", "gateway_ids": [ "123e4567e89b12d3a456wr6614175643" ], "proxy_gateway_id": "123e4567e89b12d3a456wr6614175643" } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "name": "string", "server": "string", "log_types": [ "access" ], "facility": "LOCAL0", "protocol": "TLS", "certificate_id": "3fa85f6457174562b3fc2c963f66afa6", "filter_id": "123e4567e89b12d3a456426614174000", "gateway_ids": [ "123e4567e89b12d3a456wr6614175643" ], "proxy_gateway_id": "123e4567e89b12d3a456wr6614175643", "id": "824411c22bf94e719ea757f8f3fd818e", "filter_name": "string", "created": "2021-01-27T00:00:00+00:00", "updated": "2021-01-27T00:00:00+00:00" } ``` ## Removing an Enterprise Integrations Syslog Configuration To remove an *integrations/syslog* entity, use the REST API call below: - **Method:** DELETE /api/integrations/syslog/ - **Resource:** Path If processed correctly, a confirmation is returned. Otherwise, an error is returned. ### Request The following is an example request: ```python DELETE /api/integrations/syslog/{syslog_id} Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 204 No Content Content-Type: application/json ``` # Users (users) The users entity represents a *nZTA* user. Users support the following activities: - Retrieving a user, see [Retrieving a User](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Creating a user, see [Creating a User](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Retrieving user settings, see [Retrieving User Settings](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Updating user settings, see [Updating User Settings](docId\:aL8GMecutFpZ6Qlw5Cwfp). ## Retrieving a User To retrieve the current user, use the REST API call below: - **Method:** GET /users/self - **Resource:** Path If processed correctly, a JSON body containing the current user is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python GET /users/self Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "id": "0cd145e28d483a6d57e9d73b6d78b7fe58377950", "username": "john.doe", "created": "2020-09-21T00:00:00+00:00", "updated": "2020-09-22T00:00:00+00:00" } ``` ## Creating a User To create a user entity, use the REST API call below: - **Method:** POST /users/self - **Resource:** Path - **JSON Data:** JSON dictionary representing a new user entity. If processed correctly, a JSON body containing the new user entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /users/self Authorization: Content-Type: application/json Request Body { "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com" } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com", "id": "0cd145e28d483a6d57e9d73b6d78b7fe58377950", "username": "john.doe", "created": "2020-09-21T00:00:00+00:00", "updated": "2020-09-22T00:00:00+00:00" } ``` ## Retrieving User Settings To retrieve the current user settings, use the REST API call below: - **Method:** GET /users/self/settings/ui - **Resource:** Path If processed correctly, a JSON body containing the current user settings is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```bash GET /users/self/settings/ui Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "version": "785bb486534129fd8ec732a1aa647b02d8e33491", "settings": { "on_login": { "show_welcome_wizard": false } } } ``` ## Updating User Settings To update user settings, use the REST API call below: - **Method:** PUT /users/self/settings/ui - **Resource:** Path - **JSON Data:** JSON dictionary representing new user settings. If processed correctly, a JSON body containing user settings is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /users/self/settings/ui Authorization: Content-Type: application/json Request Body { "previous_version": "h2kbb486534c49fd8ec732a1aa647b02d8e338ua", "settings": { "on_login": { "show_welcome_wizard": true } } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "version": "785bb486534129fd8ec732a1aa647b02d8e33491", "settings": { "on_login": { "show_welcome_wizard": false } } } ``` # User Rule Groups (user-rule-groups) The *user-rule-groups* entity represents a *nZTA* user rule group. User rule groups support the following activities: ## Retrieving All User Rule Groups To retrieve all *user-rule-groups* entities, use the REST API call below: - **Method:** GET /api/v1/policies/user-rule-groups - **Resource:** Path If processed correctly, a JSON body containing a list of all *user-rule-groups* entities is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```bash GET /api/v1/policies/user-rule-groups Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "items": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "description": "string", "sign_in_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sign_in_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "policy_type": "admin", "url_pattern": "string", "realm": "string", "use_as_saml_idp": true, "primary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "primary_auth_server_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Local", "name": "string" }, "secondary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "secondary_auth_server_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Local", "name": "string" }, "primary_authorization_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "role_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "role_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "admin", "name": "string", "redirect_url": "string" }, "rules": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "username", "attribute": "string", "value": "string" } ] } ] } ``` ## Creating a User Rule Group To create a *user-rule-groups* entity, use the REST API call below: - **Method:** POST /api/v1/policies/user-rule-groups - **Resource:** Path - **JSON Data:** JSON dictionary representing a new *user-rule-groups* entity. If processed correctly, a JSON body containing the new *user-rule-groups* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/v1/policies/user-rule-groups Authorization: Content-Type: application/json Request Body { "name": "string", "description": "string", "role_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sign_in_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "rules": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "username", "attribute": "string", "value": "string" } ] } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "description": "string", "sign_in_policy_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sign_in_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "policy_type": "admin", "url_pattern": "string", "realm": "string", "use_as_saml_idp": true, "primary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "primary_auth_server_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Local", "name": "string" }, "secondary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "secondary_auth_server_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Local", "name": "string" }, "primary_authorization_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "role_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "role_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "admin", "name": "string", "redirect_url": "string" }, "rules": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "username", "attribute": "string", "value": "string" } ] } ``` # User Policies (resources) A user policy is a type of *resources* entity that represents a *nZTA* user policy. User policies support the following activities: - Retrieving all user policies, see [Retrieving All User Policies](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Editing a user policy, see [Editing a User Policy](docId\:aL8GMecutFpZ6Qlw5Cwfp). :::hint{type="info" indent="1"} The *resources* entity is also used to represent a *nZTA* application. This is enabled by a **type** of "application", see [Applications (resources)](docId\:aL8GMecutFpZ6Qlw5Cwfp). ::: ## Retrieving All User Policies To retrieve all user policy (*resources*) entities, use the REST API call below: - **JSON Data:** JSON dictionary representing a *resources* type of sign-in. - **Resource:** Path - **Method:** GET /api/v1/policies/resources If processed correctly, a JSON body containing a list of all user policy resources is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python GET /api/v1/policies/resources Authorization: Content-Type: application/json Request Body { "type": "sign_in" } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "items": [ { "name": "string", "type": "sign_in", "description": "string", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sign_in_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "policy_type": "admin", "url_pattern": "string", "realm": "string", "use_as_saml_idp": true, "primary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "primary_auth_server_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Local", "name": "string" }, "secondary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "secondary_auth_server_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Local", "name": "string" }, "primary_authorization_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "app_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "access_type": "application", "resource_type": "fqdn", "resource": "string", "bookmark_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "web", "description": "string", "launch_window": true, "url": "string", "icon": "string" }, "saml_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sp_metadata": "string" } } } ] } ``` ## Editing a User Policy To edit a user policy *resources* entity, use the REST API call below: - **JSON Data:** JSON dictionary representing changed properties for a user policy *resources* entity. - **Resource:** Path - **Method:** PUT /api/v1/policies/resources/ If processed correctly, a JSON body containing the updated user policy *resources* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python PUT /api/v1/policies/resources/{resource_id} Authorization: Content-Type: application/json Request Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "sign_in", "description": "string", "sign_in_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "policy_type": "admin", "url_pattern": "string", "realm": "string", "use_as_saml_idp": true, "primary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "primary_auth_server_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Local", "name": "string" }, "secondary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "secondary_auth_server_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Local", "name": "string" }, "primary_authorization_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "app_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "access_type": "application", "resource_type": "fqdn", "resource": "string", "bookmark_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "web", "description": "string", "launch_window": true, "url": "string", "icon": "string" }, "saml_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sp_metadata": "string" } } } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "name": "string", "type": "sign_in", "description": "string", "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sign_in_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "policy_type": "admin", "url_pattern": "string", "realm": "string", "use_as_saml_idp": true, "primary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "primary_auth_server_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Local", "name": "string" }, "secondary_auth_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "secondary_auth_server_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "type": "Local", "name": "string" }, "primary_authorization_server_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "app_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "access_type": "application", "resource_type": "fqdn", "resource": "string", "bookmark_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "web", "description": "string", "launch_window": true, "url": "string", "icon": "string" }, "saml_config": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "sp_metadata": "string", "attributes": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "attribute": "string", "value": "string", "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ] } } } ``` # Retrieving Lockdown Exceptions To retrieve Lockdown exceptions, use the REST API call below: - **Method:** GET /api/clients/ui/lockdown/exceptions - **Resource:** Path If processed correctly, a JSON body containing the *exceptions* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```bash GET /api/clients/ui/lockdown/exceptions Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "total": 0, "count": 0, "items": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "description": "string", "platform": "Windows", "type": "Program", "rule_action": "Allow", "created": "string", "updated": "string", "is_default": true, "direction": "Inbound", "exception_order": 0, "port": { "protocol": "string", "remote_port": "string", "local_port": "string" }, "program": { "program_path": "string", "sha256": "string" }, "custom": { "program_path": "string", "sha256": "string", "protocol": "string", "local_port": "string", "remote_port": "string", "local_resource": "string", "remote_resource": "string" }, "program_path": "string", "protocol": "TCP", "local_port": "string", "remote_port": "string", "local_resource": "string", "remote_resource": "string" } ] } ``` # MDM Server A MDM is a type of *server* entity that represents a *nZTA* server. MDM supports the following activities: - Retrieving all MDM Servers, see [Retrieving All MDM Server](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Create MDM Server, see [Creating a MDM Serve](docId\:aL8GMecutFpZ6Qlw5Cwfp)r. - Retrieving MDM Servers by ID, see [Retrieving a MDM Server by ID](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Editing a MDM Server, see [Editing a MDM Server](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Deleting a MDM Server, see [Deleting a MDM Server](docId\:aL8GMecutFpZ6Qlw5Cwfp). ## Retrieving All MDM Servers To retrieve MDM Servers, use the REST API call below: - **Method:** GET /api/v1/policies/mdm-servers - **Resource:** Path If processed correctly, a JSON body containing the *MDM server* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```bash GET /api/v1/policies/mdm-servers Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "total": 0, "mdm_servers": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "Ivanti Cloud", "ivanti_cloud_config": { "server_url": "string", "viewer_url": "string", "request_timeout": 0, "admin_user_name": "string", "admin_password": "string", "admin_password_hash": "string", "device_identifier_template": "CN", "device_identifier_type": "UUID" }, } ] ``` ## Creating a MDM Server To Create a MDM Server entity, use the REST API call below: - **JSON Data:** JSON dictionary representing changed properties for a MDM Server entity. - **Resource:** Path - **Method:** POST /api/v1/policies/mdm-servers If processed correctly, a JSON body containing the new *MDM Server* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python POST /api/v1/policies/mdm-servers Authorization: Content-Type: application/json Request Body { "name": "string", "type": "Ivanti Cloud", "ivanti_cloud_config": { "server_url": "string", "viewer_url": "string", "request_timeout": 0, "admin_user_name": "string", "admin_password": "string", "admin_password_hash": "string", "device_identifier_template": "CN", "device_identifier_type": "UUID" }, } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "Ivanti Cloud", "ivanti_cloud_config": { "server_url": "string", "viewer_url": "string", "request_timeout": 0, "admin_user_name": "string", "admin_password": "string", "admin_password_hash": "string", "device_identifier_template": "CN", "device_identifier_type": "UUID" }, } ``` ## Retrieving a MDM Server by ID To retrieve a MDM Server by ID entity, use the REST API call below: - **JSON Data:** JSON dictionary representing changed properties for a MDM Server by ID entity. - **Resource:** Path - **Method:** GET/api/v1/policies/mdm-servers/ If processed correctly, a JSON body containing the *MDM Server by ID* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```bash GET /api/v1/policies/mdm-servers/{mdm_server_id} Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "Ivanti Cloud", "ivanti_cloud_config": { "server_url": "string", "viewer_url": "string", "request_timeout": 0, "admin_user_name": "string", "admin_password": "string", "admin_password_hash": "string", "device_identifier_template": "CN", "device_identifier_type": "UUID" }, } ``` ## Editing a MDM Server To edit a MDM Server entity, use the REST API call below: - **JSON Data:** JSON dictionary representing changed properties for a MDM Server entity. - **Resource:** Path - **Method:** PUT /api/v1/policies/mdm-servers/ If processed correctly, a JSON body containing the edited *MDM Server* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python PUT /api/v1/policies/mdm-servers/{mdm_server_id} Authorization: Content-Type: application/json Request Body { "name": "string", "type": "Ivanti Cloud", "ivanti_cloud_config": { "server_url": "string", "viewer_url": "string", "request_timeout": 0, "admin_user_name": "string", "admin_password": "string", "admin_password_hash": "string", "device_identifier_template": "CN", "device_identifier_type": "UUID" }, } ``` ### Response The following is an example response: ```python HTTP/1.1 200 OK Content-Type: application/json Response Body { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "string", "type": "Ivanti Cloud", "ivanti_cloud_config": { "server_url": "string", "viewer_url": "string", "request_timeout": 0, "admin_user_name": "string", "admin_password": "string", "admin_password_hash": "string", "device_identifier_template": "CN", "device_identifier_type": "UUID" }, } ``` ## Deleting a MDM Server To delete a *MDM Server* entity, use the REST API call below: - Method: DELETE /api/v1/policies/mdm-servers/ - Resource: Path If processed correctly, a confirmation is returned. Otherwise, an error is returned. ### Request The following is an example request: ```bash DELETE /api/v1/policies/mdm-servers/{mdm_server_id} Authorization: Content-Type: application/json ``` ### Response The following is an example response: ```python HTTP/1.1 204 Deleted MDM Server successfully Content-Type: application/json ``` # User Risk Score User Risk Score APIs manages actionable insights configurations. User Risk Score supports the following activities: - Retrieving all user risk score, see [Retrieving All User Risk Score](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Create user risk score, see [Creating a User Risk Score](docId\:aL8GMecutFpZ6Qlw5Cwfp)r. - Retrieving user risk score by ID, see [Retrieving a User Risk Score by ID](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Edit a user risk score, see [Editing a User Risk Score](docId\:aL8GMecutFpZ6Qlw5Cwfp). - Delete a user risk scorer, see [Deleting a User Risk Score](docId\:aL8GMecutFpZ6Qlw5Cwfp). ## Retrieving All User Risk Score To retrieve user risk score, use the REST API call below: - **Method:** GET /api/v1/analytics/action\_configs/user\_risk\_score - **Resource:** Path If processed correctly, a JSON body containing the *user risk score* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python curl -X 'GET' \ '/api/v1/analytics/action_configs/user_risk_score?gateway_type=zta' \ -H 'accept: application/json' ``` ### Response The following is an example response: ```python { "action_rules": [ { "action_type": "allow_next_login_with_warning", "action_params": { "terminate_active_sessions": true }, "action_threshold": 20, "action_id": "8c45a230-857e-4504-879c-3ae8c283993c", "created": 743745, "updated": 743745 } ] ``` ## Creating a User Risk Score To Create a new action rule for metric user\_risk\_score, use the REST API call below: - **JSON Data:** JSON dictionary representing changed properties for a user risk score entity. - **Resource:** Path - **Method:** POST /api/v1/analytics/action\_configs/user\_risk\_score If processed correctly, a JSON body containing the new *user risk score* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python { "action_type": "allow_next_login_with_warning", "action_params": { "terminate_active_sessions": true }, "action_threshold": 20 } ``` ### Response The following is an example response: ```python { "action_type": "allow_next_login_with_warning", "action_params": { "terminate_active_sessions": true }, "action_threshold": 20, "action_id": "8c45a230-857e-4504-879c-3ae8c283993c", "created": 743745, "updated": 743745 } ``` ## Retrieving a User Risk Score by ID To retrieve a user risk score by ID entity, use the REST API call below: - **JSON Data:** JSON dictionary representing changed properties for a user risk score by ID entity. - **Resource:** Path - **Method:** GET/api/v1/analytics/action\_configs/user\_risk\_score/ If processed correctly, a JSON body containing the *user risk score by ID* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python curl -X 'GET' \ '/api/v1/analytics/action_configs/user_risk_score/e274bf3ebe3841a88ade1630515624c6?gateway_type=zta' \ -H 'accept: application/json' ``` ### Response The following is an example response: ```python { "action_type": "allow_next_login_with_warning", "action_params": { "terminate_active_sessions": true }, "action_threshold": 20, "action_id": "8c45a230-857e-4504-879c-3ae8c283993c", "created": 743745, "updated": 743745 } ``` ## Editing a User Risk Score To edit a user risk score entity, use the REST API call below: - **JSON Data:** JSON dictionary representing changed properties for a user risk score entity. - **Resource:** Path - **Method:** PUT /api/v1/analytics/action\_configs/user\_risk\_score/ If processed correctly, a JSON body containing the edited *user risk score* entity is returned. Otherwise, a JSON body containing an error is returned. ### Request The following is an example request: ```python curl -X 'PUT' \ '/api/v1/analytics/action_configs/user_risk_score/e274bf3ebe3841a88ade1630515624c6?gateway_type=zta' \ -H 'accept: application/json' \ -H 'Content-Type: application/json' \ -d '{ "action_type": "allow_next_login_with_warning", "action_params": { "terminate_active_sessions": true }, "action_threshold": 20, "action_id": "8c45a230-857e-4504-879c-3ae8c283993c" }' ``` ### Response The following is an example response: ```python { "action_type": "allow_next_login_with_warning", "action_params": { "terminate_active_sessions": true }, "action_threshold": 20, "action_id": "8c45a230-857e-4504-879c-3ae8c283993c", "created": 743745, "updated": 743745 } ``` ## Deleting a User Risk Score To delete a *user risk score *entity, use the REST API call below: - Method: DELETE /api/v1/analytics/action\_configs/user\_risk\_score/ - Resource: Path If processed correctly, a confirmation is returned. Otherwise, an error is returned. ### Request The following is an example request: ```python curl -X 'DELETE' \ '/api/v1/analytics/action_configs/user_risk_score/e274bf3ebe3841a88ade1630515624c6?gateway_type=zta' \ -H 'accept: */*' ``` ### Response The following is an example response: ```python 204 Deleted MDM Server successfully ``` # Storage Consumption ## Total Storage Consumption for a Tenant ### Request The following is an example request: ```python GET /api/licenses/subscriptions/storage-consumption ``` ### Response The following is an example response: ```python { "total_bytes": 15, "computed_at": "2025-07-29T09:14:24Z" } ``` ## Per-backend Breakdown for a Tenant in a Cluster ### Request The following is an example request: ```python GET /api/licenses/tenants/{tenant_id}/storage-consumption ``` ### Response The following is an example response: ```python { "tenant_id": 42045, "postgres_bytes": 10000, "elasticsearch_bytes": 10000, "blobstore_bytes": 10000, "total_bytes": 30000, "computed_at": "2025-07-29T09:14:24Z" } ```