IP Protect Configuration API v1

IP Protect shields your site from DDoS attacks by diverting traffic and scrubbing network packets.

Learn more:


Overview

IP Protect helps shield your site from DDoS attacks: attempts to disrupt your website by overwhelming it with Internet traffic. With IP Protect that isn’t a problem, because most Internet traffic doesn’t go directly to your website. Instead:

  1. Akamai diverts traffic bound for your site to a collection of Akamai virtual IP addresses, typically referred to as VIPs. IP Protect uses DNS records to point your domain name to these addresses.
  2. Akamai routes traffic through a scrubbing center. The scrubbing center removes network packets that are likely to be DDoS attack vectors.
  3. Akamai’s Management IPs, also known as MIPs, send the sanitized traffic to your website.

Because the malicious traffic is neutralized in the scrubbing center, the DDoS attack never reaches your site.

Use the IP Protect Configuration API to manage your virtual IP addresses and to help monitor your network infrastructure.

Get started

To configure this API for the first time:

  • Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akaa-ubmkk7nvwnkoc3ur-v6xslqlze3yi3k5u.luna.akamaiapis.net.

  • To enable this API, choose the API service named Prolexic IP Protect Config API, and set the access level to READ-WRITE.

API concepts

To understand this API and the data it exchanges, familiarize yourself with these concepts:

  • Policy domains. Policy domains are administrative partitions within IP Protect. Partitioning enables Policy Domain A to have a different configuration and a different set of administrators than Policy Domain B. Currently, the Akamai services team creates policy domains for you. When Akamai creates a policy domain, values are also set for the number of virtual IP addresses available for use, and the number of ports you can configure on those addresses.

  • Virtual IP addresses. When you subscribe to IP Protect, Akamai assigns a set of virtual IP addresses that you match to your internal web servers. For example, you might map the virtual IP address 192.168.1.1 to your internal IP address 10.0.0.1. By modifying DNS records, you then direct incoming Internet traffic to the VIP address 192.168.1.1 instead of your internal address. The virtual IP address receives the incoming traffic and routes that traffic through an Akamai scrubbing center. The scrubbing center removes any DDoS packets and then forwards the sanitized traffic to your internal servers by using an Akamai Management IP address. That’s the good news. The even better news? This routing and rerouting adds an average of just six milliseconds to a web transaction. Note that compliance and security concerns require you to keep virtual IP addresses for the length of your contract. There’s no way to return unused or unneeded virtual IP addresses without engaging your Akamai account team.

  • Back-end IPs. IP addresses of the servers and subnets on your internal network. Administrators match each Akamai virtual IP address to one of your back-end IP addresses, using either the IP Protect API or Control Center. Each server or subnet requiring protection on your network is mapped to a virtual IP address.

  • Management IP addresses. Forwards processed traffic from an Akamai scrubbing center to your internal network. As much as possible, configure your firewalls to only accept incoming transmission from the Akamai Management IP addresses.

  • Ports. Ports open for network connections. You can specify port assignments using any of these methods:

    • Individually. For example: 443.
    • As a comma-delimited string of ports: 80, 443, 867.
    • As a range of ports: 80-150.
    • As a combination of individual ports and ranges of ports: 80, 100-120, 443, 600-800.

    The preceding examples allow both TCP and UDP traffic. You can limit a port to accepting only TCP or UDP traffic by using syntax similar to this:

    TCP/90, UDP/900

    IP Protect also works with these non-ported protocols:

    • GRE. Generic Routing Encapsulation.
    • ESP. Encapsulating Security Protocol.
    • ICMP. Internet Control Messaging Protocol for IPv4 addresses. Use ICMPv6 for IPv6 addresses.
    • AH. Authentication Header.

    To use any of the non-ported protocols, include the protocol identifier preceded by IP/. For example, this syntax enables the use of the ICMP protocol:

    IP/ICMP

  • Configuration. Detailed information about a policy domain, including the domain’s subnets and virtual IP addresses.

  • Health status. Health status for a back-end IP, based on the percentage of active locations for the IP address. IP Protect calculates health status by using these criteria:

    Percentage of Active Locations Health Status
    Greater than or equal to 70% Healthy
    30% to 69% Possible connectivity issues
    1% to 29% Connectivity issues
    0% Down
    Location percentage not available Unknown

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
List mapped IP addresses GET /ip-protect/v1/mips
List policy domains GET /ip-protect/v1/policy-domains{?latest}
Get a policy domain GET /ip-protect/v1/policy-domains/{pdName}{?extended}
List policy configurations GET /ip-protect/v1/policy-domains/{pdName}/configs{?latest}
Create a new configuration version POST /ip-protect/v1/policy-domains/{pdName}/configs
Allocate subnets PUT /ip-protect/v1/policy-domains/{pdName}/pd-subnets/allocate
Get health status for a policy domain GET /ip-protect/v1/policy-domains/{pdName}/vips/health-stats{?startTime,endTime}
List virtual IP addresses POST /ip-protect/v1/policy-domains/vips
Get health status POST /ip-protect/v1/policy-domains/vips/health-stats

List mapped IP addresses

Returns IP address ranges for the Akamai Management IP subnets. The Management IPs forward sanitized traffic from an Akamai scrubbing center to your network.

GET /ip-protect/v1/mips

Status 200 application/json

Download schema: MipOutput.json

Response body:

[
    "72.52.0.0/18",
    "23.57.96.0/20",
    "209.200.128.0/18"
]

List policy domains

Returns summary information for your policy domains, including information about each domain’s configurations and subnets.

GET /ip-protect/v1/policy-domains{?latest}

Sample: /ip-protect/v1/policy-domains?latest=true

Parameter Type Sample Description
Optional query parameters
latest Boolean true Returns only the latest set of configuration values for each policy domain. Omit this parameter or set it to false to include all the available configuration value sets in the API response.

Status 200 application/json

Object type: PolicyDomain

Download schema: OpenSummary.json

Response body:

[
    {
        "createdTimestamp": "2020-05-08T15:45:48.242+0000",
        "createdBy": "gms",
        "updatedTimestamp": null,
        "updatedBy": null,
        "policyDomainName": "documentation_na",
        "vipsLimit": 100,
        "pdId": 10731,
        "portsLimit": 150,
        "configVersions": [
            {
                "createdTimestamp": "2020-05-13T22:08:58.272+0000",
                "createdBy": "gms",
                "updatedTimestamp": null,
                "updatedBy": null,
                "deployState": "deployed",
                "configVersionId": 265,
                "ipsAllocated": 40,
                "ipsConfigured": 17,
                "pdSubnets": [
                    {
                        "pdSubnetId": 308,
                        "pdSubnet": "10.0.0.8/29",
                        "legacyPdSubnet": false,
                        "vips": []
                    },
                    {
                        "pdSubnetId": 307,
                        "pdSubnet": "10.0.0.96/27",
                        "legacyPdSubnet": false,
                        "vips": [
                            247,
                            248
                        ]
                    }
                ]
            }
        ]
    }
]

Get a policy domain

Returns summary information for the specified policy domain. Use the extended parameter to return information about the number of virtual IP addresses available to, and configured for, the domain.

GET /ip-protect/v1/policy-domains/{pdName}{?extended}

Sample: /ip-protect/v1/policy-domains/documentation_na?extended=true

Parameter Type Sample Description
URL path parameters
pdName String documentation_na Unique name of the policy domain.
Optional query parameters
extended Boolean true Causes the ipsAllocated and ipsConfigured values to appear in the API response. The ipsAllocated value indicates the number of virtual IP addresses available to a domain, while the ipsConfigured value is the number of virtual IP address configured for use. These two values don’t appear in the API response if you omit the extended parameter or set the parameter value to false.

Status 200 application/json

Object type: PolicyDomain

Download schema: SettingUpdateOpenOutput.json

Response body:

{
    "createdTimestamp": "2020-04-29T21:02:02.942+0000",
    "createdBy": "gms",
    "updatedTimestamp": "2020-04-29T21:02:22.570+0000",
    "updatedBy": "gms",
    "policyDomainName": "documentation_na",
    "pdId": 52,
    "vipsLimit": 303,
    "portsLimit": 150,
    "configVersions": [
        {
            "configVersionId": 27,
            "ipsAllocated": 4,
            "ipsConfigured": 2
        }
    ]
}

List policy configurations

Returns configuration information for the specified policy domain. By default, this operation returns all the available configuration sets. Use the latest parameter to return only the most recent set of configuration values.

GET /ip-protect/v1/policy-domains/{pdName}/configs{?latest}

Sample: /ip-protect/v1/policy-domains/documentation_na/configs?latest=true

Parameter Type Sample Description
URL path parameters
pdName String documentation_na Unique name of the policy domain.
Optional query parameters
latest Boolean true Returns only the latest set of configuration values for the policy domain. Omit this parameter or set it to false to return all the available configuration value sets for the domain.

Status 200 application/json

Object type: Config

Download schema: AllConfigOpenOutput.json

Response body:

[
    {
        "configVersionId": 1,
        "deployState": "edited",
        "createdBy": "gms",
        "createdTimestamp": "2020-04-29T21:02:02.942+0000",
        "updatedBy": null,
        "updatedTimestamp": null,
        "ipsAllocated": 32,
        "ipsConfigured": 20,
        "pdSubnets": [
            {
                "pdSubnetId": 1,
                "configVersionId": 1,
                "pdSubnet": "1.1.1.4/26",
                "legacyPdSubnet": false,
                "vips": [
                    {
                        "vipId": 1,
                        "customerBackend": "2.2.2.2/28",
                        "akamaiFrontend": "1.1.1.4/28",
                        "ports": "80, 443",
                        "type": "PASSTHROUGH",
                        "sourceIpProtocol": "PROXY_PROTOCOL_V2",
                        "legacyVip": false
                    }
                ]
            }
        ]
    }
]

Create a new configuration version

Creates a new configuration version for the specified policy domain. This operation adds new virtual IP addresses and creates or deletes subnets as needed.

POST /ip-protect/v1/policy-domains/{pdName}/configs

Sample: /ip-protect/v1/policy-domains/documentation_na/configs

Content-Type: application/json

Object type: Config

Download schema: CreateOrDeployConfigOpen.json

Request body:

{
    "pdSubnets": [
        {
            "pdSubnet": "1.2.3.4/30",
            "legacyPdSubnet": false,
            "vips": [
                {
                    "customerBackend": "2.2.2.2/31",
                    "akamaiFrontend": "1.2.3.4/31",
                    "ports": "80, 443",
                    "sourceIpProtocol": "PROXY_PROTOCOL_V2",
                    "legacyVip": false
                },
                {
                    "customerBackend": "4.4.4.4/31",
                    "akamaiFrontend": "1.2.3.6/31",
                    "ports": "TCP/80-100,120-150,IP/AH",
                    "sourceIpProtocol": "PROXY_PROTOCOL_V1",
                    "legacyVip": false
                }
            ]
        },
        {
            "pdSubnet": "1.2.3.8/32",
            "legacyPdSubnet": false
        },
        {
            "pdSubnet": "1.2.3.9/32",
            "legacyPdSubnet": true,
            "vips": [
                {
                    "customerBackend": "5.5.5.5/32",
                    "akamaiFrontend": "1.2.3.9/32",
                    "ports": "TCP/80-100,UDP/1000-2000,120-150,IP/AH,",
                    "sourceIpProtocol": "NA",
                    "legacyVip": true
                }
            ]
        }
    ]
}
Parameter Type Sample Description
URL path parameters
pdName String documentation_na Unique name of the policy domain.

Status 200 application/json

Object type: Config

Download schema: DeployOutputOpen.json

Response body:

{
    "createdTimestamp": "2020-11-13T16:04:27.905+00:00",
    "createdBy": "gms",
    "updatedTimestamp": "2020-11-13T16:04:27.905+00:00",
    "updatedBy": "gms",
    "pdName": "documentation_na",
    "deployState": "deploying",
    "pdSubnets": [
        {
            "pdSubnetId": 2951,
            "pdSubnet": "1.2.3.4/30",
            "legacyPdSubnet": false,
            "vips": [
                {
                    "vipId": 1678,
                    "customerBackend": "2.2.2.2/31",
                    "akamaiFrontend": "1.2.3.4/31",
                    "ports": "80,443",
                    "type": "PASSTHROUGH",
                    "sourceIpProtocol": "PROXY_PROTOCOL_V2",
                    "legacyVip": false
                },
                {
                    "vipId": 1679,
                    "customerBackend": "4.4.4.4/31",
                    "akamaiFrontend": "1.2.3.6/31",
                    "ports": "120-150,IP/AH,TCP/80-100",
                    "type": "PASSTHROUGH",
                    "sourceIpProtocol": "PROXY_PROTOCOL_V1",
                    "legacyVip": false
                }
            ]
        },
        {
            "pdSubnetId": 2952,
            "pdSubnet": "1.2.3.8/32",
            "legacyPdSubnet": false,
            "vips": null
        },
        {
            "pdSubnetId": 2953,
            "pdSubnet": "1.2.3.9/32",
            "legacyPdSubnet": false,
            "vips": [
                {
                    "vipId": 1680,
                    "customerBackend": "5.5.5.5/32",
                    "akamaiFrontend": "1.2.3.9/32",
                    "ports": "120-150,IP/AH,TCP/80-100,UDP/1000-2000",
                    "type": "PASSTHROUGH",
                    "sourceIpProtocol": "NA",
                    "legacyVip": false
                }
            ]
        }
    ]
}

Allocate subnets

Adds virtual IP addresses to the specified policy domain. In the request body, use addVips to specify the number of virtual IP addresses you’re adding, and use allocateIpv6 to configure the IP addressing type for these addresses. Set allocateIpv6 to true to use IPv6 addressing, and either omit allocateIpv6 or set the value to false to use IPv4 addressing.

PUT /ip-protect/v1/policy-domains/{pdName}/pd-subnets/allocate

Sample: /ip-protect/v1/policy-domains/documentation_na/pd-subnets/allocate

Content-Type: application/json

Object type: Allocation

Download schema: addVipsSchema.json

Request body:

{
    "addVips": 5,
    "allocateIpv6": true
}
Parameter Type Sample Description
URL path parameters
pdName String documentation_na Unique name of the policy domain.

Status 200 application/json

Object type: Config

Download schema: UpdatePdSubnetOpenResponse.json

Response body:

{
    "configVersionId": 1,
    "pdName": "documentation_na",
    "deployState": "deployed",
    "createdBy": "gms",
    "createdTimestamp": "2020-04-29T21:02:02.942+0000",
    "updatedBy": null,
    "updatedTimestamp": null,
    "ipsAllocated": 32,
    "ipsConfigured": 20,
    "pdSubnets": [
        {
            "pdSubnetId": 1,
            "pdSubnet": "1.1.1.4/26",
            "legacyPdSubnet": false,
            "vips": [
                {
                    "vipId": 1,
                    "customerBackend": "2.2.2.2/28",
                    "akamaiFrontend": "1.1.1.4/28",
                    "ports": "80, 443",
                    "type": "PASSTHROUGH",
                    "sourceIpProtocol": "PROXY_PROTOCOL_V2"
                }
            ]
        }
    ]
}

Get health status for a policy domain

Returns the health status for the specified policy domain. Health status measures the percentage of locations for a backend IP address that are currently available. IP Protect calculates separate health status scores for each back-end address.

GET /ip-protect/v1/policy-domains/{pdName}/vips/health-stats{?startTime,endTime}

Sample: /ip-protect/v1/policy-domains/documentation_na/vips/health-stats?startTime=1614274795000&endTime=1616693995000

Parameter Type Sample Description
URL path parameters
pdName String documentation_na Unique name of the policy domain.
Optional query parameters
endTime Number 1616693995000 Timestamp in Unix epoch milliseconds of the latest set of health statistics you want to return. If you omit the endTime parameter, the health status interval automatically extends to the current time.
startTime Number 1614274795000 Timestamp in Unix epoch milliseconds of the earliest set of health statistics you want to return. Akamai retains health statistics for seven days.

Status 200 application/json

Object type: HealthStatus

Download schema: BackendStatusOutput.json

Response body:

[
    {
        "policyDomainName": "documentation_na",
        "vips": [
            {
                "vipId": 836,
                "akamaiFrontEnd": "10.176.176.78/31",
                "customerBackend": "112.251.11.0/31",
                "backendIps": [
                    {
                        "backendIp": "112.251.11.0",
                        "status": "down"
                    },
                    {
                        "backendIp": "112.251.11.1",
                        "status": "healthy"
                    }
                ]
            },
            {
                "vipId": 835,
                "akamaiFrontEnd": "10.176.176.76/31",
                "customerBackend": "110.251.11.0/31",
                "backendIps": [
                    {
                        "backendIp": "110.251.11.0",
                        "status": "unknown"
                    },
                    {
                        "backendIp": "110.251.11.1",
                        "status": "unknown"
                    }
                ]
            }
        ]
    }
]

List virtual IP addresses

Returns information about the specified virtual IP addresses. Include the IDs of those virtual IP addresses in the vipIds array in the request body.

POST /ip-protect/v1/policy-domains/vips

Content-Type: application/json

Download schema: VipIdInput.json

Request body:

{
    "vipIds": [
        1781,
        1782,
        1783
    ]
}

Status 200 application/json

Object type: VirtualIp

Download schema: VipIdOutput.json

Response body:

[
    {
        "createdTimestamp": "2020-11-18T23:36:45.183+00:00",
        "createdBy": "gms",
        "updatedTimestamp": "2020-11-18T23:36:45.183+00:00",
        "updatedBy": "gms",
        "vipId": 1781,
        "customerBackend": "1.1.1.110/32",
        "akamaiFrontend": "10.176.176.110/32",
        "ports": "80,IP/AH,IP/ESP,IP/GRE,IP/ICMP",
        "serviceType": "PASSTHROUGH",
        "sourceIpProtocol": "PROXY_PROTOCOL_V2",
        "pdSubnetId": 3126,
        "pdSubnet": "10.176.176.110/31",
        "legacyVip": false
    },
    {
        "createdTimestamp": "2020-11-18T23:36:45.184+00:00",
        "createdBy": "gms",
        "updatedTimestamp": "2020-11-18T23:36:45.184+00:00",
        "updatedBy": "gms",
        "vipId": 1782,
        "customerBackend": "1.1.1.111/32",
        "akamaiFrontend": "10.176.176.111/32",
        "ports": "80,IP/AH,IP/ESP,IP/GRE,IP/ICMP",
        "serviceType": "PASSTHROUGH",
        "sourceIpProtocol": "PROXY_PROTOCOL_V1",
        "pdSubnetId": 3126,
        "pdSubnet": "10.176.176.110/31",
        "legacyVip": false
    },
    {
        "createdTimestamp": "2020-11-18T23:36:45.185+00:00",
        "createdBy": "gms",
        "updatedTimestamp": "2020-11-18T23:36:45.185+00:00",
        "updatedBy": "gms",
        "vipId": 1783,
        "customerBackend": "1.2.3.4/30",
        "akamaiFrontend": "10.176.176.104/30",
        "ports": "1-51,IP/AH,IP/ESP,IP/GRE,IP/ICMP",
        "serviceType": "PASSTHROUGH",
        "sourceIpProtocol": "NA",
        "pdSubnetId": 3127,
        "pdSubnet": "10.176.176.104/30",
        "legacyVip": false
    }
]

Get health status

Returns the health status for the specified policy domains. List domain names in the customers array in the request body. You can also use startTime and endTime to define a health status time interval, beginning with the startTime and ending with the endTime. Be sure to use Unix epoch milliseconds when specifying these values. If you do not include endTime the time interval automatically extends to the current time. Akamai retains health statistics for seven days.

POST /ip-protect/v1/policy-domains/vips/health-stats

Content-Type: application/json

Object type: HealthStatus

Download schema: BackendStatusInput.json

Request body:

{
    "customers": [
        "documentation_na"
    ],
    "startTime": 1599152694000,
    "endTime": 1599152699000
}

Status 200 application/json

Object type: HealthStatus

Download schema: BackendStatusOutput.json

Response body:

[
    {
        "policyDomainName": "documentation_na",
        "vips": [
            {
                "vipId": 836,
                "akamaiFrontEnd": "10.176.176.78/31",
                "customerBackend": "112.251.11.0/31",
                "backendIps": [
                    {
                        "backendIp": "112.251.11.0",
                        "status": "down"
                    },
                    {
                        "backendIp": "112.251.11.1",
                        "status": "healthy"
                    }
                ]
            },
            {
                "vipId": 835,
                "akamaiFrontEnd": "10.176.176.76/31",
                "customerBackend": "110.251.11.0/31",
                "backendIps": [
                    {
                        "backendIp": "110.251.11.0",
                        "status": "unknown"
                    },
                    {
                        "backendIp": "110.251.11.1",
                        "status": "unknown"
                    }
                ]
            }
        ]
    }
]

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

This section’s data schema tables list membership requirements as follows:

Member is required in requests, or always present in responses, even if its value is empty or null.
Member is optional, and may be omitted in some cases.

PolicyDomain

Administrative partitions for IP Protect.

Download schema: SettingUpdateOpenOutput.json

Sample GET response:

{
    "createdTimestamp": "2020-04-29T21:02:02.942+0000",
    "createdBy": "gms",
    "updatedTimestamp": "2020-04-29T21:02:22.570+0000",
    "updatedBy": "gms",
    "policyDomainName": "documentation_na",
    "pdId": 52,
    "vipsLimit": 303,
    "portsLimit": 150,
    "configVersions": [
        {
            "configVersionId": 27,
            "ipsAllocated": 4,
            "ipsConfigured": 2
        }
    ]
}

PolicyDomain members

Member Type Description
PolicyDomain: Administrative partitions for IP Protect.
configVersions PolicyDomain.configVersions[] Virtual IP address allocations and configurations for the policy domain.
createdBy String Username of the person responsible for creating the policy domain.
createdTimestamp String ISO 8061 timestamp indicating the creation time of the policy domain.
pdId Integer Unique identifier of the policy domain.
policyDomainName String Unique name of the policy domain.
portsLimit String Maximum number of TCP or UDP ports configurable on a single virtual IP address.
updatedBy String Username of the person responsible for the most-recent update of the policy domain.
updatedTimestamp String ISO 8061 timestamp indicating the most-recent update time of the policy domain.
vipsLimit String Number of virtual IP addresses available to the policy domain.
PolicyDomain.configVersions[]: Virtual IP address allocations and configurations for the policy domain.
configVersionId Number Unique identifier of the configuration version.
ipsAllocated Number Number of virtual IP addresses allocated for the policy domain.
ipsConfigured Number Number of virtual IP addresses configured for the policy domain.

Config

Information about the virtual IP addresses found in an Akamai virtual subnet.

Download schema: CreateOrDeployConfig.json

Sample POST request:

{
    "pdSubnets": [
        {
            "pdSubnet": "1.2.3.4/30",
            "legacyPdSubnet": false,
            "vips": [
                {
                    "customerBackend": "2.2.2.2/31",
                    "akamaiFrontend": "1.2.3.4/31",
                    "ports": "80, 443",
                    "sourceIpProtocol": "PROXY_PROTOCOL_V2",
                    "legacyVip": false
                },
                {
                    "customerBackend": "4.4.4.4/31",
                    "akamaiFrontend": "1.2.3.6/31",
                    "ports": "TCP/80-100,120-150,IP/AH",
                    "sourceIpProtocol": "PROXY_PROTOCOL_V1",
                    "legacyVip": false
                }
            ]
        },
        {
            "pdSubnet": "1.2.3.8/32",
            "legacyPdSubnet": false
        },
        {
            "pdSubnet": "1.2.3.9/32",
            "legacyPdSubnet": true,
            "vips": [
                {
                    "customerBackend": "5.5.5.5/32",
                    "akamaiFrontend": "1.2.3.9/32",
                    "ports": "TCP/80-100,UDP/1000-2000,120-150,IP/AH,",
                    "sourceIpProtocol": "NA",
                    "legacyVip": true
                }
            ]
        }
    ]
}

Config members

Member Type Description
Config: Information about the virtual IP addresses found in an Akamai virtual subnet.
pdSubnets Config.pdSubnets[] Subnets for the virtual IP addresses.
version Integer Information about the virtual IP addresses found in an Akamai virtual subnet.
Config.pdSubnets[]: Subnets for the virtual IP addresses.
legacyPdSubnet Boolean Indicates whether IP Protect’s predecessor, Prolexic Proxy, was responsible for creating the subnet.
pdSubnet String Unique identifier of the subnet.
vips Config.pdSubnets[].vips[] Virtual IP addresses. IP Protect directs Internet traffic to these addresses.
Config.pdSubnets[].vips[]: Virtual IP addresses. IP Protect directs Internet traffic to these addresses.
akamaiFrontend String Virtual IP address that’s been mapped to a customer’s server or subnet.
customerBackend String IP address of a customer’s server or subnet that’s been mapped to a virtual IP address.
legacyVip Boolean Indicates whether IP Protect’s predecessor, Prolexic Proxy, was responsible for creating the virtual IP address.
ports String Ports open to traffic directed to a customer’s website.
sourceIpProtocol Enumeration Specifies the source IP for network packets received at a customer’s back-end server or subnet. By default, packets are set to NA, identifying Akamai as the source IP. Other source IP options are NAT46, CIP, PROXY_PROTOCOL_V1, PROXY_PROTOCOL_V2, and OPTION_28. NAT46 is only available if the virtual IP address has an IPv4 address and the back-end server or subnet has an IPv6 address. The remaining options require the virtual IP address to be running on a TCP network.

Allocation

Specifies the number and type of the IP addresses you want to allocate.

Download schema: addVipsSchema.json

Sample PUT request:

{
    "addVips": 5,
    "allocateIpv6": true
}

Allocation members

Member Type Required Description
Allocation: Specifies the number and type of the IP addresses you want to allocate.
addVips Integer Number of virtual IP addresses to allocate.
allocateIpv6 Boolean Indicates that the new virtual IP addresses use IPv6 addressing. If you omit this parameter or set it to false, the new addresses use IPv4 addressing.

HealthStatus

Reports the health status of the back-end IP addresses in your policy domains.

Download schema: BackendStatusOutput.json

Sample GET response:

[
    {
        "policyDomainName": "documentation_na",
        "vips": [
            {
                "vipId": 836,
                "akamaiFrontEnd": "10.176.176.78/31",
                "customerBackend": "112.251.11.0/31",
                "backendIps": [
                    {
                        "backendIp": "112.251.11.0",
                        "status": "down"
                    },
                    {
                        "backendIp": "112.251.11.1",
                        "status": "healthy"
                    }
                ]
            },
            {
                "vipId": 835,
                "akamaiFrontEnd": "10.176.176.76/31",
                "customerBackend": "110.251.11.0/31",
                "backendIps": [
                    {
                        "backendIp": "110.251.11.0",
                        "status": "unknown"
                    },
                    {
                        "backendIp": "110.251.11.1",
                        "status": "unknown"
                    }
                ]
            }
        ]
    }
]

HealthStatus members

Member Type Description
HealthStatus: Reports the health status of the back-end IP addresses in your policy domains.
policyDomainName String Unique name of the policy domain.
vips HealthStatus.vips[] Virtual IP addresses. IP Protect routes traffic to these virtual IP addresses.
HealthStatus.vips[]: Virtual IP addresses. IP Protect routes traffic to these virtual IP addresses.
akamaiFrontend String IP address of the Akamai virtual IP address that’s been mapped to a customer’s server or subnet IP address.
backendIps HealthStatus.vips[].backendIps[] IP addresses of a customer’s servers and subnets.
customerBackend String IP address of the customer’s server or subnet.
vipId Integer Unique identifier of the Akamai virtual IP address.
HealthStatus.vips[].backendIps[]: IP addresses of a customer’s servers and subnets.
backendIp String IP addresses of a customer’s server or subnet.
status Enumeration Current state of the back-end IP. Valid values are HEALTHY, POSSIBLE_CONNECTIVITY_ISSUES, CONNECTIVITY_ISSUES, DOWN, and UNKNOWN. IP Protect calculates health status by determining the percentage of active locations for a back-end IP address.

VirtualIp

Virtual IP addresses.

Download schema: VipIdOutput.json

Sample POST response:

[
    {
        "createdTimestamp": "2020-11-18T23:36:45.183+00:00",
        "createdBy": "gms",
        "updatedTimestamp": "2020-11-18T23:36:45.183+00:00",
        "updatedBy": "gms",
        "vipId": 1781,
        "customerBackend": "1.1.1.110/32",
        "akamaiFrontend": "10.176.176.110/32",
        "ports": "80,IP/AH,IP/ESP,IP/GRE,IP/ICMP",
        "serviceType": "PASSTHROUGH",
        "sourceIpProtocol": "PROXY_PROTOCOL_V2",
        "pdSubnetId": 3126,
        "pdSubnet": "10.176.176.110/31",
        "legacyVip": false
    },
    {
        "createdTimestamp": "2020-11-18T23:36:45.184+00:00",
        "createdBy": "gms",
        "updatedTimestamp": "2020-11-18T23:36:45.184+00:00",
        "updatedBy": "gms",
        "vipId": 1782,
        "customerBackend": "1.1.1.111/32",
        "akamaiFrontend": "10.176.176.111/32",
        "ports": "80,IP/AH,IP/ESP,IP/GRE,IP/ICMP",
        "serviceType": "PASSTHROUGH",
        "sourceIpProtocol": "PROXY_PROTOCOL_V1",
        "pdSubnetId": 3126,
        "pdSubnet": "10.176.176.110/31",
        "legacyVip": false
    },
    {
        "createdTimestamp": "2020-11-18T23:36:45.185+00:00",
        "createdBy": "gms",
        "updatedTimestamp": "2020-11-18T23:36:45.185+00:00",
        "updatedBy": "gms",
        "vipId": 1783,
        "customerBackend": "1.2.3.4/30",
        "akamaiFrontend": "10.176.176.104/30",
        "ports": "1-51,IP/AH,IP/ESP,IP/GRE,IP/ICMP",
        "serviceType": "PASSTHROUGH",
        "sourceIpProtocol": "NA",
        "pdSubnetId": 3127,
        "pdSubnet": "10.176.176.104/30",
        "legacyVip": false
    }
]

VirtualIp members

Member Type Required Description
VirtualIp: Virtual IP addresses.
akamaiFrontend String IP address of the Akamai virtual IP that’s been mapped to a customer’s server or subnet.
createdBy String Username of the person responsible for allocating the virtual IP address.
createdTimestamp String ISO 8601 timestamp indicating the creation time of the virtual IP address.
customerBackend String IP address of a customer’s server or subnet.
legacyVip Boolean Indicates whether IP Protect’s predecessor, Prolexic Proxy, was responsible for creating the virtual IP address.
pdSubnet String Virtual IP address of the subnet.
pdSubnetId Number Unique identifier of the virtual IP subnet.
ports String Comma-delimited string of ports open to Internet traffic.
sourceIpProtocol Enumeration Specifies the source IP for network packets received at a customer’s back-end server or subnet. By default, packets are set to NA, identifying Akamai as the source IP. Other source IP options are NAT46, CIP, PROXY_PROTOCOL_V1, PROXY_PROTOCOL_V2, and OPTION_28. NAT46 is only available if the virtual IP address has an IPv4 address and the back-end IP has an IPv6 address. The remaining options require the virtual IP address to be running on a TCP network.
type String IP address of a customer’s server or subnet that’s been mapped to a virtual IP address.
updatedBy String Username of the person responsible for the most recent update of the virtual IP address.
updatedTimestamp String ISO 8601 timestamp indicating the most recent update of the virtual IP address.
vipId Number Unique identifier of the virtual IP address.

Errors

This section provides details on the data object that reflects the API’s common response to error cases. It also lists the API’s range of response status codes for both error and success cases.

Error responses

If an error case occurs, this API responds with a JSON object similar to this:

{
    "errorCode": "EXCEEDS_LIMIT",
    "message": "The value addVips = 100 exceeds the limit set to this policy-domain. Kindly provide a value less than 100.",
    "args": [
        "addVips",
        100,
        100
    ]
}

See HTTP status codes for a list of error codes.

HTTP status codes

This section lists the full range of response codes the API might generate.

Code Description
200 The operation was successful.
400 Bad Request. This typically occurs due to a problem with the format of the request data, such as invalid JSON syntax in the request body.
401 Authentication failure. See Get started for guidance on how to correctly set up your API hostname token.
403 Access is forbidden. This usually reflects a limitation on the identity of the user employing the API client. See Get started to make sure you have permission to access all the functionality you need.
404 Resource not found. This typically occurs when an item in a URL path parameter no longer exists or hasn’t been correctly referenced.
405 Method not supported. This often occurs when the URL you’re calling responds to GET requests, but not to PUT or DELETE requests.
500 Internal server error.
501 Functionality not supported.
502 Platform timeout error.
503 Too many requests. Service is temporarily unavailable.