--- title: "External HTTPS calls" slug: "external-https-calls-v7-0" description: "Learn how to configure scripts in AppGate ZTNA for REST calls, caching, and user claims while ensuring secure external service interactions." tags: ["External HTTPS calls", "Scripts"] updated: 2026-06-05T19:17:40Z published: 2026-06-05T19:17:40Z canonical: "support.appgate.com/external-https-calls-v7-0" --- > ## Documentation Index > Fetch the complete documentation index at: https://support.appgate.com/llms.txt > Use this file to discover all available pages before exploring further. # External HTTPS calls When configuring scripts, you can make REST calls to external web services to return values such as IP addresses or true/false results.The behavior depends on where the call is made: - In a condition's access criteria or a policy's assignment expressions, the call returns only true/false. It is not a means of setting a claim value within AppGate ZTNA. - In a user claim script, the returned claim can be used in criteria expressions on both Controllers and Gateways. The JavaScript engine used in AppGate ZTNA is a modified version of [Oracle's Nashorn](http://www.oracle.com/technetwork/articles/java/jf14-nashorn-2126515.html). ## Available functions HTTP calls and HTTP redirections are not permitted. Only HTTPS is supported by default. To enable HTTP, use the appropriate `cz-config` command. Because the engine runs in a sandbox, it does not provide the `XMLHttpRequest` object. Use the following REST helper functions instead: ```javascript // conditions and policy assignment can use helper methods to interact with third party REST servers. // get request functions httpGet(url) httpGet(url, headers) httpGet(url, headers, timeout) // post request functions httpPost(url, data) httpPost(url, data, contentType) httpPost(url, data, contentType, headers) httpPost(url, data, contentType, headers, timeout) // put request functions httpPut(url, data)sc httpPut(url, data, contentType) httpPut(url, data, contentType, headers) httpPut(url, data, contentType, headers, timeout) // delete request functions httpDelete(url) httpDelete(url, headers) httpDelete(url, headers, timeout) // printing output in "Test" mode console.log(message) // default values contentType = application/JSON timeout = 3000 headers = no value // creating custom headers var headers = [  {'key':'header-name1', 'value':'header-value1'},  {'key':'header-name2', 'value':'header-value2'}, ]; ``` ## Cache functions A caching feature lets you reuse results without making repeated HTTPS calls. Cache methods work on both Controllers (user and criteria scripts) and Gateways (condition and entitlement scripts). The cache is local to each appliance and shared across all users. If the first user on a Gateway populates a cache object, subsequent users can use the same object. You can also use `username` or group claim objects such as `claim.objectX` to cache objects per user or per group. The cache stores entries as a key, value, and timestamp. If a value is absent or has expired, the provided function retrieves the object and stores it in the cache. There is no command to clear the cache manually; it is re-evaluated when the script rerun. ```javascript // cache functions cache.get(key, functionToGetIfItsNotInCache) // will pass 1 day validity cache.get(key, functionToGetIfItsNotInCache, validityDurationSeconds) cache.getIfPresent(key) // will return the cached value if it hasn't expired. Otherwise null cache.put(key, value) // will pass 1 day validity cache.put(key, value, validityDurationSeconds) ``` ## Code examples ### Check user identity and location The following example checks that the username is `test`, the phone number starts with `+44`, and the client IP resolves to Great Britain (GB). ```javascript var result; var location = httpGet("https://ipinfo.io/" + claims.system.clientSrcIP + "/country").data; console.log("resolved location: " + location); result = claims.user.username === "test"; result = result && claims.user.phone && claims.user.phone.toString().startsWith("+44"); result = result &&  location == "GB"; return result; ``` ### Query the Controller using the REST API The following example authenticates to the Controller and retrieves allocated tunnel IPs for a given distinguished name ```javascript // example code:  ============= var controllerUrl = 'https://controller.company.com:8443'; // admin interface or the controller(s) var headers = [  {'key':'Accept', 'value':'application/vnd.appgate.peer-v18+JSON'}, ]; // the api user must be extempt from Admin-OTP requirement in Global Settings var signinData = {  'machineId': 'f0031c00-0522-43b3-a642-ae23cfd1bc22',  'providerName': 'local',  'username': 'api-username',  'password': 'api-user-password' }; var signinReq = httpPost(controllerUrl + '/admin/login', JSON.stringify(signinData), 'application/JSON', headers); if(signinReq.statusCode != 200){  console.log('ERROR during sign-in: ' + signinReq.statusCode);  return false; } // add authorization token to the headers headers.push({'key': 'authorization', 'value': 'Bearer ' + JSON.parse(signinReq.data).token}); // now any controller rest interface can be used directly // for example, fetch tun IPs   var tunIpReq = httpGet(controllerUrl + '/admin/ip-pools/allocated-ips/by-dn/OU=local', headers); if(tunIpReq.statusCode != 200) {  console.log('ERROR during query: ' + tunIpReq.statusCode);  return false; } // set allocations variable to data object in JSON result var allocations = JSON.parse(tunIpReq.data).data; // print the ipAddress for each allocation allocations.forEach((x, i) => console.log(x.ipAddress)) return false; ``` ### Cache GithHub IP addresses for one week The following example retrieves GitHub API IP addresses and caches them for seven days. ```javascript return cache.get('github IPs', // name of the cache entry                 () => JSON.parse(httpGet('https://api.github.com/meta').data).api, // if the IPs are not present in the cache or have expired, this is a function to get them and place them to the cache.                 60 * 60 * 24 * 7); // how long the entry should be kept in the cache (7 days) ``` ### Download and cache endpoints from a JSON file The following example downloads endpoints from a JSON file for use in entitlement scripts. It caches the results for 24 hours but attempts to refresh the data every 15 minutes. If the download fails after 15 minutes, the script uses the cached data. If the download succeeds, the script updates the cache. ```javascript const fieldName = "File Server"; const JSONUrl = "https://myserver.com/api/static/scripted_file_server.JSON"; const cutOffMinutes = 15; const cacheMinutes  = 24 * 60; const lastUpdated = cache.getIfPresent(fieldName + "_lastupdated") || false; // use the cache if it is newer than cutOffMinutes if (lastUpdated && (new Date() - lastUpdated) < (cutOffMinutes * 60000)) {  return cache.getIfPresent(fieldName) || []; } // if cache is older than cutOffMinutes, fetch again let response = httpGet(JSONUrl, 1500); if (response && response.statusCode == 200) {  const endpoints = JSON.parse(response.data); // store the value in cache for 24 hours  cache.put(fieldName, endpoints[fieldName], 60 * cacheMinutes);  cache.put(fieldName + "_lastupdated", new Date()); } return cache.getIfPresent(fieldName) || []; ``` ### Security note Scripts may need credentials to request information from external systems. Those credentials must be included in the JavaScript. Scripts used in entitlements and conditions are passed in the encrypted portion of the entitlement token. ### Disclaimer Any scripts provided by the AppGate ZTNA Professional Services team or included as examples in this manual are delivered as-is, without warranty of any kind. AppGate ZTNA disclaims all implied warranties, including any implied warranties of merchantability or fitness for a particular purpose. The customer is responsible for any maintenance arising from the use or performance of these sample scripts and related documentation.