API Documentation
The internet-safeguarding API, which firewalls use to obtain EDLs, follows a simple request structure:
For VPN’s and other related data sets for EDLs the common structure is:
https://api.internet-safeguarding.com/vpapi/[tier]/[data]/[options]/{parameters}
The [tier] is the service tier you have purchased, valid tiers are:
Free, Basic, Enhanced, Premium.
More details on the tiers and their entitlement can be found here:
The free tier requires registration and a contractual arrangement to abide by terms of use etc. even though it’s ‘free’.
The valid API data & options paths for the /vpapi/ endpoint are:
| /[data]/ | Description | Valid Options |
| tor | EDL’s of IP addresses to allow / block Tor. | ipv4, ipv6, ipcombined |
| publicdns | EDLs of IP addresses to allow / block public recursive DNS servers. | ipv4, ipv6 |
| apple | EDL to block Apple Private Relay. | dnshosts |
| vpn * | EDLs of IP addresses, URLs and DNS names to allow / block commercial VPNs. Includes Apple above. | ipv4, ipv6, uri, ffipv4, ffipv6, dnshosts |
| wificalling | EDLs of IP addresses to allow / block to enable wifi calling. | ipv4, ipv6, ipcombined |
| AS | EDLs of IP address prefixes advertised by AS Numbers in CIDR format. Reserved ASNs return a comment # Reserved. Note that an IP address CIDR may appear in multiple ASs. | ipv4, ipv6, ipcombined. A list or single AS number must also be in the parameters, &asn=. |
Not all options are available in all tiers & supported VPNs vary by tier.
Note: If you use an IP combined EDL, or mix IPv4 and IPv6 EDLs in the same firewall policy line / rule, please double check that your firewall is enforcing those rules correctly.
Parameters:
You must specify a valid FW_Type and Auth_Token as parameters, some datasets may require additional parameters as detailed above and in the examples.
See Configuring EDL’s on your firewall. for selecting a valid Firewall / FW_Type.
Some example valid API calls:
The Auth_Token is your specific service key.
| GET https://api.internet-safeguarding.com/vpapi/enhanced/vpn/ipv4/?FW_Type=paloalto&Auth_Token=FFFFFFFF-1111-0000-2222-111122223333 Returns an EDL of the main IPv4 addresses for blocking commercial VPNs. |
| GET https://api.internet-safeguarding.com/vpapi/enahced/vpn/ffipv4/?FW_Type=paloalto&Auth_Token=FFFFFFFF-1111-0000-2222-111122223333 Returns a small additional EDL of the Fast Flux IPv4 addresses for blocking the most dynamic commercial VPNs. |
| GET https://api.internet-safeguarding.com/vpapi/enhanced/AS/ipcombined/?FW_Type=paloalto&Auth_Token=FFFFFFFF-1111-0000-2222-111122223333&asn=AS99%3BAS9%3BAS999%3BAS7 or GET https://api.internet-safeguarding.com/vpapi/enhanced/AS/ipcombined/?FW_Type=paloalto&Auth_Token=FFFFFFFF-1111-0000-2222-111122223333&asn=AS99,AS9,AS999, AS7 Depending on your your firewall handles encoding. or GET https://api.internet-safeguarding.com/vpapi/enhanced/AS/ipcombined/?list=FW_Type~paloalto.Auth_Token=FFFFFFFF-1111-0000-2222-111122223333.asn~AS99,AS9,AS999,AS7 Returns a combined IPv4 and IPv6 EDL for AS numbers 99, 9, 999 and 7, %3B is an encoded “,” character You may also use the “;” character to separate the list of queried ASNs. Any spaces you include in the ASN list are automatically removed. Reserved ASNs return a # Reserved comment. |
| GET https://api.internet-safeguarding.com/vpapi/free/vpn/dnshosts/?list=FW_Type~paloalto.Auth_Token~FFFFFFFF-1111-0000-2222-111122223333 Returns an EDL of the DNS hosts to block in addition to IP addresses to block commercial VPN’s in the free tier, this request uses and alternative parameter format where all the parameters in in a single list parameter. |
Note: Some firewalls have issues with correctly encoding some EDL requests with multiple parameters and encode the & in the parameters section incorrectly, causing a 500 error from the API.
API responses & HTTP response codes:
| HTTP Response Code | Description |
| 200 | Success, the response body / attachment will contain the data / EDL. In the case of invalid, reserved or unused / defunct AS numbers, a 200 is returned, with any valid data for valid AS numbers, invalid AS numbers or an empty AS parameter list silently return no data. |
| 4nn | Something was wrong with the request. The body may indicate more about what cause the error. |
| 403 | Forbidden, incorrect API key or similar error, incorrect tier, option or data keys, or invalid combination. The API will return a body attachment with more detail about the error. |
| 404 | Resource Not Found, incorrect API request structure. |
| 429 | Rate Limit Exceeded. |
| 5nn 500 | Something was wrong with the request and the server had an error processing that request, or there is a server fault. Incorrectly encoded & in parameters is a common cause of this error. |
EDL Refresh period:
| EDL Data | Recommended EDL Refresh | Update Frequency and notes |
| tor | Hourly | Hourly, Dynamic |
| publicdns | Daily | Real Time data source |
| apple | Weekly | Real Time data source, very static data. |
| vpn – ipv4/ipv6/ipcombined/url/dnshosts | Hourly | Real Time data source – Large list, dynamic |
| vpn – ffipv4/ffipv6/ffipcombined/ | 15 Minutes – 5 Minutes – (1 or 2 Minute if your FW can handle it and you have issues with FF VPN’s, see VPN supported list for details.) | Real Time data source – very small list, extremely dynamic. May also be an empty list. |
| AS | Daily / Hourly | Every 4 Hours |
| wificalling | Daily / Hourly | Real Time data source, infrequent changes. |