Enterprise Threat Protector Configuration API Resources

This section provides details on each API operation.

The following list provides a road map of all the conceptual objects you deal with when interacting with the Enterprise Threat Protector (ETP) Configuration API, and provides pointers to where you can learn more.

  • Configuration: When you sign up for ETP, you receive a configuration and associated ID. This configuration contains settings for all of your sites, such as locations, policies, and quick lists.

  • Site: A site is a named collection of public IP addresses that belong to a region or geographic area in your network, such as a CIDR block for an office branch or company headquarters. Use sites to compare the query’s source IP with the IPs of configured sites. A site configuration must include the IP address of your Active Directory or other local DNS server used to communicate with ETP. See the Site object type.

  • Policy: A policy is the rule set that defines how Enterprise Threat Protector (ETP) handles known or suspected DNS threats. You assign a policy to a location or you can assign multiple locations to a policy. See the Policy object type.

  • DNS Provisioning: Defines the IPv4 and IPv6 address information for the primary and secondary DNS recursive servers that are assigned to you. These DNS servers forward traffic from users to Akamai. See the DnsConfiguration object type.

  • Response: When ETP receives a DNS query, it sends back a response. The responses must match the original query, which verifies there is a valid mapping from query type to response type.

  • Category: The type of detected threat. The threat type can be malware, phishing, command and control (C&C), or an other category.

  • Lists: A list is a Set of domain and IP addresses that are known or suspected to be malicious for a specific category of threat.
    • Akamai Lists: By default, each policy is configured with Akamai Security Lists. These security lists contain domains and IP addresses verified as threats in the category assigned to the list. Various network security resources are used to maintain and update these lists.

    • Emergency Lists: Emergency lists are a fast and easy way to allow or deny domains or IP addresses in your network. You can add domains and IP addresses to a blacklist to block access or you can add the domains or IP addresses into the whitelist to permit access. You can add a maximum of 1,000 entries to each list. See the EmergencyList object type.

    • Custom Lists: In a custom list configuration, you define the known and suspected domains and IP addresses for a policy. Like the security lists, a custom list is assigned to a policy by default. You also select the action that Enterprise Threat Protector (ETP) completes to handle a known or suspected threat to your network. See the CustomList object type.

  • List Quota: When creating a custom list, each domain or IP address entry is counted. ETP allows you to have a total of 200,000 custom list entries. See the ListQuota object type.

  • List Deployment: After applying configuration changes to a custom list, you must deploy these changes to the ETP network to ensure the changes take effect. Changes typically deploy in 30 minutes. For example, when you add or modify a list item, the changes are not propagated until the deploy operation is complete. See the ListDeployment object type.

  • Accepted Usage Policy (AUP): Defines how how ETP handles violations to an Acceptable Use Policy (AUP). ETP enforces the policy by denying DNS queries from sources that have deemed inappropriate in the AUP, and returns an error page in response. ETP includes AUP categories for content that is traditionally blocked with an enterprise. See the Policy.aupSettings[n] object type.

  • Honeypot: A honeypot action directs a known or suspected malicious domain or IP address to a security device that monitors activity and collects information regarding the domain or IP address. When creating or editing a policy, you have the option to select a sinkhole as the action for the list. See the Honeypot object type.

  • Configuration Deployment: After applying configuration changes to a site, policy, emergency list, or honeypot, you must deploy these changes to the Enterprise Threat Protector (ETP) network to ensure the changes take effect. Changes typically deploy within 20–30 seconds. For example, when you add or modify a location, the configuration changes are not propagated to the ETP network until the deploy operation is complete. See the ConfigurationDeployment object type.

  • Certificate: TLS certificates allow you to establish a secure connection using the public key provided by your certificate authority (CA). You can specify an Akamai-issued certificate or a customer-provisioned certificate using a trusted third-party CA. See the Certificate object type.

API Summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Built-in Lists  
Get All Akamai Built-in Security Lists GET /etp-config/v1/akamai-lists
Responses  
List Akamai Built-in Responses GET /etp-config/v1/responses
AUP Categories  
List AUP Category Predefined Configurations GET /etp-config/v1/aup-categories
Security Categories  
List Security Category Predefined Configurations GET /etp-config/v1/security-categories
Configurations  
List Configurations GET /etp-config/v1/configs
List DNS Provisioning Configurations GET /etp-config/v1/configs/{configId}/dnsConfiguration
List Sites GET /etp-config/v1/configs/{configId}/sites
Create a Site POST /etp-config/v1/configs/{configId}/sites
Get a Site GET /etp-config/v1/configs/{configId}/sites/{siteId}
Update a Site PUT /etp-config/v1/configs/{configId}/sites/{siteId}
Remove a Site DELETE /etp-config/v1/configs/{configId}/sites/{siteId}
List Policies GET /etp-config/v1/configs/{configId}/policies
Create a Policy POST /etp-config/v1/configs/{configId}/policies
Get a Policy GET /etp-config/v1/configs/{configId}/policies/{policyId}
Update a Policy PUT /etp-config/v1/configs/{configId}/policies/{policyId}
Remove a Policy DELETE /etp-config/v1/configs/{configId}/policies/{policyId}
Get All Lists GET /etp-config/v1/configs/{configId}/lists
Create a List POST /etp-config/v1/configs/{configId}/lists
Get Global List Quota GET /etp-config/v1/configs/{configId}/lists/quota
Get a List GET /etp-config/v1/configs/{configId}/lists/{listId}
Update a List PUT /etp-config/v1/configs/{configId}/lists/{listId}
Remove a List DELETE /etp-config/v1/configs/{configId}/lists/{listId}
Patch a List PATCH /etp-config/v1/configs/{configId}/lists/{listId}
Search in a List GET /etp-config/v1/configs/{configId}/lists/items{?numItemsPerPage,page,type,confidence,search}
Modify List Items PUT /etp-config/v1/configs/{configId}/lists/items
List Recent Changes GET /etp-config/v1/configs/{configId}/lists/recentChanges
Get All List Deployments GET /etp-config/v1/configs/{configId}/lists/deployments
Create a List Deployment POST /etp-config/v1/configs/{configId}/lists/deployments
Get a List Deployment GET /etp-config/v1/configs/{configId}/lists/deployments/{listDeploymentId}
Get all Emergency Lists GET /etp-config/v1/configs/{configId}/emergency-lists
Get an Emergency List GET /etp-config/v1/configs/{configId}/emergency-lists/{listType}
Update an Emergency List PUT /etp-config/v1/configs/{configId}/emergency-lists/{listType}
List Honeypots GET /etp-config/v1/configs/{configId}/honeypots
Create a Honeypot POST /etp-config/v1/configs/{configId}/honeypots
Get a Honeypot GET /etp-config/v1/configs/{configId}/honeypots/{honeypotId}
Update a Honeypot PUT /etp-config/v1/configs/{configId}/honeypots/{honeypotId}
Remove a Honeypot DELETE /etp-config/v1/configs/{configId}/honeypots/{honeypotId}
List Configuration Deployments GET /etp-config/v1/configs/{configId}/deployments
Create a Configuration Deployment POST /etp-config/v1/configs/{configId}/deployments
Get a Configuration Deployment GET /etp-config/v1/configs/{configId}/deployments/{configDeploymentId}
Get Recent Changes GET /etp-config/v1/configs/{configId}/recentChanges
Certificates  
List Certificates GET /etp-config/v1/tls/customers/{configId}/certificates{?debug,include-certificate}
Create a New Certificate POST /etp-config/v1/tls/customers/{configId}/certificates
Get a Certificate GET /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}{?debug,include-certificate}
Modify a Certificate PUT /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}
Activate a Certificate POST /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}/op/activate
Deactivate a Certificate POST /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}/op/deactivate
Confirm Download POST /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}/op/confirm-download
Confirm Distribute POST /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}/op/confirm-distribution

Get All Akamai Built-in Security Lists

Returns a list of all available Akamai built-in Lists.

GET /etp-config/v1/akamai-lists

Status 200 application/json

Response Body:

[
    {
        "id": 110,
        "name": "Akamai List",
        "description": "Akamai's List",
        "securityCategoryId": 1,
        "securityCategoryInfo": {
            "id": 1,
            "name": "Malware"
        }
    }
]

List Akamai Built-in Responses

Returns a list of all available Akamai built-in responses.

GET /etp-config/v1/responses

Status 200 application/json

Response Body:

[
    {
        "id": 2,
        "name": "Deny",
        "description": "Deny",
        "allowedForAUP": false
    }
]

List AUP Category Predefined Configurations

Returns a list of all available predefined AUP categories.

GET /etp-config/v1/aup-categories

Status 200 application/json

Response Body:

[
    {
        "id": 1,
        "name": "Social",
        "description": "Social"
    }
]

List Security Category Predefined Configurations

Returns a list of all available predefined security categories

GET /etp-config/v1/security-categories

Status 200 application/json

Response Body:

[
    {
        "id": 3,
        "name": "C&C",
        "description": "C&C"
    }
]

List Configurations

Returns a list of ETP configuration IDs. Use this value for a configId parameter in subsequent operations.

GET /etp-config/v1/configs

Status 200 application/json

Response Body:

[
    1,
    2
]
  1. Make a GET request to /etp-config/v1/configs.

List DNS Provisioning Configurations

Returns a list of DNS provisioning configurations.

GET /etp-config/v1/configs/{configId}/dnsConfiguration

Sample: /etp-config/v1/configs/342/dnsConfiguration

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200 application/json

Response Body:

{
    "ipv4Addrs": {
        "primary": "192.168.10.10",
        "secondary": "192.160.10.20"
    },
    "ipv6Addrs": {
        "primary": "2021:D32::88/124",
        "secondary": "2021:D32::89/124"
    }
}
  1. Run List Configurations to retrieve a specific configId.

  2. Make a GET request to /etp-config/v1/configs/{configId}/dnsConfiguration.

List Sites

Returns a list of all Sites for a configuration.

GET /etp-config/v1/configs/{configId}/sites

Sample: /etp-config/v1/configs/342/sites

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200 application/json

Response Body:

[
    {
        "id": 101,
        "description": "This is Akamai's site 1",
        "name": "Akamai Site 1",
        "exitPoints": [
            {
                "ipAddr": "10.10.10.10",
                "addrType": "ADDR_TYPE_IPV4"
            }
        ],
        "policyId": 1030,
        "policyInfo": {
            "id": 1030,
            "name": "Policy 1"
        }
    },
    {
        "id": 102,
        "description": "This is Akamai's site 2",
        "name": "Akamai Site 2",
        "exitPoints": [
            {
                "ipAddr": "20.20.20.20",
                "addrType": "ADDR_TYPE_IPV4"
            }
        ],
        "policyId": 1040,
        "policyInfo": {
            "id": 1040,
            "name": "Policy 2"
        }
    }
]
  1. Run List Configurations to retrieve a specific configId.

  2. Make a GET request to /etp-config/v1/configs/{configId}/sites.

Create a Site

Creates a new site.

POST /etp-config/v1/configs/{configId}/sites

Sample: /etp-config/v1/configs/342/sites

Content-Type: application/json

Request Body:

{
    "description": "This is Akamai's site",
    "name": "Akamai Site 1",
    "exitPoints": [
        {
            "ipAddr": "10.10.10.10",
            "addrType": "ADDR_TYPE_IPV4"
        }
    ],
    "policyId": 1030
}
Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200

Get a Site

Returns the details of a specific Site.

GET /etp-config/v1/configs/{configId}/sites/{siteId}

Sample: /etp-config/v1/configs/342/sites/101

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
siteId Integer 101 A unique identifier for a site.

Status 200 application/json

Response Body:

{
    "id": 101,
    "description": "This is Akamai's site",
    "name": "Akamai Site",
    "exitPoints": [
        {
            "ipAddr": "10.10.10.10",
            "addrType": "ADDR_TYPE_IPV4"
        }
    ],
    "policyId": 1030,
    "policyInfo": {
        "id": 1030,
        "name": "Policy 1"
    }
}
  1. Run List Configurations to retrieve a specific configId.

  2. Run List Sites to retrieve a specific siteId.

  3. Make a GET request to /etp-config/v1/configs/{configId}/sites/{siteId}.

Update a Site

Modifies Site details.

PUT /etp-config/v1/configs/{configId}/sites/{siteId}

Sample: /etp-config/v1/configs/342/sites/101

Content-Type: application/json

Request Body:

{
    "description": "This is Akamai's site",
    "name": "Akamai Site 1",
    "exitPoints": [
        {
            "ipAddr": "10.10.10.10",
            "addrType": "ADDR_TYPE_IPV4"
        }
    ],
    "policyId": 1030
}
Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
siteId Integer 101 A unique identifier for a site.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. Run List Sites to retrieve a specific siteId.

  3. Run Get a Site to retrieve a Site object.

  4. Modify the Site object.

  5. Make a PUT request to /etp-config/v1/configs/{configId}/sites/{siteId}.

Remove a Site

Deletes a specific site.

DELETE /etp-config/v1/configs/{configId}/sites/{siteId}

Sample: /etp-config/v1/configs/342/sites/101

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
siteId Integer 101 A unique identifier for a site.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. Run List Sites to retrieve a specific siteId.

  3. Make a DELETE request to /etp-config/v1/configs/{configId}/sites/{siteId}.

List Policies

Returns a list of all Policies.

GET /etp-config/v1/configs/{configId}/policies

Sample: /etp-config/v1/configs/342/policies

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200 application/json

Response Body:

[
    {
        "id": 1050,
        "description": "Akamai's Policy",
        "name": "Akamai Policy",
        "sites": [
            101,
            102
        ],
        "sitesInfo": [
            {
                "id": 101,
                "name": "Akamai Site 1"
            },
            {
                "id": 102,
                "name": "Akamai Site 2"
            }
        ]
    }
]
  1. Run List Configurations to retrieve a specific configId.

  2. Make a GET request to /etp-config/v1/configs/{configId}/policies.

Create a Policy

Creates a new policy.

POST /etp-config/v1/configs/{configId}/policies

Sample: /etp-config/v1/configs/342/policies

Content-Type: application/json

Request Body:

{
    "description": "Akamai's Policy",
    "name": "Akamai Policy",
    "sites": [
        100
    ],
    "basicSettings": {
        "dnssec": false,
        "edns0ecs": false
    },
    "aupSettings": [
        {
            "categoryId": 2,
            "responseId": 2
        }
    ],
    "securitySettings": [
        {
            "listId": 1,
            "confirmedResponseId": 1,
            "suspectedResponseId": 1,
            "shouldNotifyConfirmed": true,
            "shouldNotifySuspected": true
        }
    ]
}
Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200

Get a Policy

Returns the details of a specific Policy.

GET /etp-config/v1/configs/{configId}/policies/{policyId}

Sample: /etp-config/v1/configs/342/policies/1040

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
policyId Integer 1040 A unique identifier for the policy.

Status 200 application/json

Response Body:

{
    "id": 115,
    "description": "Akamai's Policy",
    "name": "Akamai Policy",
    "sites": [
        100
    ],
    "sitesInfo": [
        {
            "id": 100,
            "name": "Akamai Site"
        }
    ],
    "basicSettings": {
        "dnssec": true,
        "edns0ecs": true
    },
    "aupSettings": [
        {
            "categoryId": 1,
            "categoryInfo": {
                "id": 1,
                "name": "Social"
            },
            "responseId": 1,
            "responseInfo": {
                "id": 1,
                "name": "Monitor"
            }
        }
    ],
    "securitySettings": [
        {
            "listId": 1,
            "listInfo": {
                "id": 1,
                "name": "Akamai List"
            },
            "confirmedResponseId": 2,
            "confirmedResponseInfo": {
                "id": 2,
                "name": "Deny"
            },
            "suspectedResponseId": 1,
            "suspectedResponseInfo": {
                "id": 1,
                "name": "Monitor"
            },
            "shouldNotifyConfirmed": true,
            "shouldNotifySuspected": true
        }
    ]
}
  1. Run List Configurations to retrieve a specific configId.

  2. Run List Policies to retrieve a specific policyId.

  3. Make a GET request to /etp-config/v1/configs/{configId}/policies/{policyId}.

Update a Policy

Modifies a Policy’s details.

PUT /etp-config/v1/configs/{configId}/policies/{policyId}

Sample: /etp-config/v1/configs/342/policies/1040

Content-Type: application/json

Request Body:

{
    "id": 120,
    "description": "Akamai's Policy",
    "name": "Akamai Policy",
    "sites": [
        100
    ],
    "basicSettings": {
        "dnssec": false,
        "edns0ecs": false
    },
    "aupSettings": [
        {
            "categoryId": 2,
            "responseId": 2
        }
    ],
    "securitySettings": [
        {
            "listId": 1,
            "confirmedResponseId": 1,
            "suspectedResponseId": 1,
            "shouldNotifyConfirmed": true,
            "shouldNotifySuspected": true
        }
    ]
}
Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
policyId Integer 1040 A unique identifier for the policy.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. Run List Policies to retrieve a specific policyId.

  3. Run Get a Policy to retrieve a Policy object.

  4. Modify the Policy object.

  5. Make a PUT request to /etp-config/v1/configs/{configId}/policies/{policyId}.

Remove a Policy

Deletes a specific policy.

DELETE /etp-config/v1/configs/{configId}/policies/{policyId}

Sample: /etp-config/v1/configs/342/policies/1040

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
policyId Integer 1040 A unique identifier for the policy.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. Run List Policies to retrieve a specific policyId.

  3. Make a DELETE request to /etp-config/v1/configs/{configId}/policies/{policyId}.

Get All Lists

Returns a list of all available custom security lists.

GET /etp-config/v1/configs/{configId}/lists

Sample: /etp-config/v1/configs/342/lists

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200 application/json

Response Body:

[
    {
        "id": 225,
        "name": "Akamai List",
        "description": "Akamai's List",
        "securityCategoryId": 2,
        "securityCategoryInfo": {
            "id": 2,
            "name": "Phishing"
        },
        "itemCount": 800,
        "knownCounts": {
            "ips": 200,
            "domains": 200
        },
        "suspectedCounts": {
            "ips": 200,
            "domains": 200
        }
    }
]
  1. Run List Configurations to retrieve a specific configId.

  2. Make a GET request to /etp-config/v1/configs/{configId}/lists.

Create a List

Creates a new List.

POST /etp-config/v1/configs/{configId}/lists

Sample: /etp-config/v1/configs/342/lists

Content-Type: application/json

Request Body:

{
    "securityCategoryId": 1,
    "name": "Example List name",
    "description": "A short description of the example List"
}
Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200

Get Global List Quota

Returns the remaining list item quota for all lists globally.

GET /etp-config/v1/configs/{configId}/lists/quota

Sample: /etp-config/v1/configs/342/lists/quota

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200 application/json

Response Body:

{
    "count": 1000,
    "remainingCount": 990
}
  1. Run List Configurations to retrieve a specific configId.

  2. Make a GET request to /etp-config/v1/configs/{configId}/lists/{quota}.

  3. View the returned ListQuota object.

Get a List

Returns the details of a specific List.

GET /etp-config/v1/configs/{configId}/lists/{listId}

Sample: /etp-config/v1/configs/342/lists/225

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
listId Integer 225 A unique identifier for the list. Use this value for a listId parameter in subsequent operations.

Status 200 application/json

Response Body:

{
    "id": 225,
    "name": "Akamai List",
    "securityCategoryId": 2,
    "securityCategoryInfo": {
        "id": 2,
        "name": "Phishing"
    },
    "description": "Akamai's List",
    "itemCount": 800,
    "knownCounts": {
        "ips": 200,
        "domains": 200
    },
    "suspectedCounts": {
        "ips": 200,
        "domains": 200
    },
    "remainingCount": 200
}
  1. Run List Configurations to retrieve a specific configId.

  2. Run Get All Lists to retrieve a specific listId.

  3. Make a GET request to /etp-config/v1/configs/{configId}/lists/{listId}.

Update a List

Modifies list properties and all items for a specific list. Full update only.

PUT /etp-config/v1/configs/{configId}/lists/{listId}

Sample: /etp-config/v1/configs/342/lists/225

Content-Type: application/json

Request Body:

{
    "name": "Akamai List",
    "securityCategoryId": 1,
    "description": "Akamai's List"
}
Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
listId Integer 225 A unique identifier for the list. Use this value for a listId parameter in subsequent operations.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. Run Get All Lists to retrieve a specific listId.

  3. Run Get a List to retrieve a CustomList object.

  4. Modify the CustomList object.

  5. Make a PUT request to /etp-config/v1/configs/{configId}/lists/{listId}.

Remove a List

Deletes a specific list.

DELETE /etp-config/v1/configs/{configId}/lists/{listId}

Sample: /etp-config/v1/configs/342/lists/225

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
listId Integer 225 A unique identifier for the list. Use this value for a listId parameter in subsequent operations.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. Run Get All Lists to retrieve a specific listId.

  3. Make a DELETE request to /etp-config/v1/configs/{configId}/lists/{listId}.

Patch a List

Modifies individual list items entries. Add or delete only.

PATCH /etp-config/v1/configs/{configId}/lists/{listId}

Sample: /etp-config/v1/configs/342/lists/225

Content-Type: application/json

Request Body:

{
    "delete": [
        "192.160.100.100",
        "220.10.100.11"
    ],
    "add": [
        {
            "type": "LIST_TYPE_IP",
            "value": "115.65.10.134",
            "confidenceLevelId": 2
        }
    ]
}
Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
listId Integer 225 A unique identifier for the list. Use this value for a listId parameter in subsequent operations.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. Run Get All Lists to retrieve a specific listId.

  3. Create a ListPatch object.

  4. Make a PATCH request to /etp-config/v1/configs/{configId}/lists/{listId}.

Search in a List

Filters items in a list by search parameters (Optional).

GET /etp-config/v1/configs/{configId}/lists/items{?numItemsPerPage,page,type,confidence,search}

Sample: /etp-config/v1/configs/342/lists/items?numItemsPerPage=25&page=1&type=192.168.0.10&confidence=2&search=192.168.1.100

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
Optional Query Parameters
confidence Integer 2 The confidence level of the results. A value of 1 signifies a suspected item, while a value of 2 signifies a known item. The default value of 0 signifies both confidence values.
numItemsPerPage Integer 25 The number of items per page.
page Integer 1 The page number to fetch.
search String 192.168.1.100 Search The string within the results.
type String 192.168.0.10 The target domain or IP address to search.

Status 200 application/json

Response Body:

{
    "items": [
        {
            "type": "LIST_TYPE_IP",
            "value": "192.168.0.10",
            "confidenceLevelId": 1
        }
    ],
    "totalCount": 200
}
  1. Run List Configurations to retrieve a specific configId.

  2. Select appropriate values for the numItemsPerPage,page, type, confidence, and search query parameters. See this operation’s parameters for details.

  3. Make a GET request to /etp-config/v1/configs/{configId}/lists/items{?numItemsPerPage,page,type,confidence,search}.

Modify List Items

Updates list items (overwrite).

PUT /etp-config/v1/configs/{configId}/lists/items

Sample: /etp-config/v1/configs/342/lists/items

Content-Type: application/json

Request Body:

[
    {
        "type": "LIST_TYPE_IP",
        "value": "192.168.100.100",
        "confidenceLevelId": 1
    }
]
Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. Modify the ListItem object.

  3. Make a PUT request to /etp-config/v1/configs/{configId}/lists/items.

List Recent Changes

Returns a list of all changes made to customer lists since the previous list deployment.

GET /etp-config/v1/configs/{configId}/lists/recentChanges

Sample: /etp-config/v1/configs/342/lists/recentChanges

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200 application/json

Response Body:

{
    "created": [
        {
            "id": 1,
            "name": "Akamai 1"
        }
    ],
    "deleted": [
        {
            "id": 2,
            "name": "Akamai 2"
        }
    ],
    "modified": [
        {
            "id": 3,
            "name": "Akamai 3"
        }
    ]
}
  1. Run List Configurations to retrieve a specific configId.

  2. Make a GET request to /etp-config/v1/configs/{configId}/lists/recentChanges.

Get All List Deployments

Returns a list of all changes made to customer lists since the last list deployment.

GET /etp-config/v1/configs/{configId}/lists/deployments

Sample: /etp-config/v1/configs/342/lists/deployments

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200 application/json

Response Body:

[
    {
        "id": 101,
        "status": "COMPLETED",
        "message": "File successfully deployed to Akamai network (Succeeded)",
        "startTime": "2016-09-23",
        "endTime": "2016-09-23",
        "deployedBy": "internal-user"
    }
]
  1. Run List Configurations to retrieve a specific configId.

  2. Make a GET request to /etp-config/v1/configs/{configId}/lists/deployments.

Create a List Deployment

Creates a new lists deployment.

POST /etp-config/v1/configs/{configId}/lists/deployments

Sample: /etp-config/v1/configs/342/lists/deployments

Content-Type: application/json

Request Body:

{
    "id": 102,
    "status": "PENDING"
}
Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200

Get a List Deployment

Returns the details of a specific list deployment.

GET /etp-config/v1/configs/{configId}/lists/deployments/{listDeploymentId}

Sample: /etp-config/v1/configs/342/lists/deployments/101

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
listDeploymentId Integer 101 A unique ID for the list deployment. Use this value for a listDeploymentId parameter in subsequent operations.

Status 200 application/json

Response Body:

{
    "id": 101,
    "status": "COMPLETED",
    "message": "File successfully deployed to Akamai network (Succeeded)",
    "startTime": "2012-04-23T18:22:43.511Z",
    "endTime": "2012-04-23T18:25:43.511Z",
    "deployedBy": "internal-user"
}
  1. Run List Configurations to retrieve a specific configId.

  2. Run Get All List Deployments to retrieve a specific deploymentId.

  3. Make a GET request to /etp-config/v1/configs/{configId}/lists/deployments/{deploymentId}.

Get all Emergency Lists

Returns the whitelist and blacklist, including entries.

GET /etp-config/v1/configs/{configId}/emergency-lists

Sample: /etp-config/v1/configs/342/emergency-lists

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200 application/json

Response Body:

{
    "whitelist": {
        "ipAddrs": [
            "192.160.10.10",
            "10.12.22.33"
        ],
        "domains": [
            "www.akamai.com",
            "www.google.com"
        ]
    },
    "blacklist": {
        "ipAddrs": [
            "172.16.77.80",
            "188.111.10.11"
        ],
        "domains": [
            "www.malwaresite.com",
            "www.phishingsite.com"
        ]
    }
}
  1. Run List Configurations to retrieve a specific configId.

  2. Make a GET request to /etp-config/v1/configs/{configId}/emergency-lists.

Get an Emergency List

Returns an emergency list by type. Valid values are whitelist or blacklist.

GET /etp-config/v1/configs/{configId}/emergency-lists/{listType}

Sample: /etp-config/v1/configs/342/emergency-lists/whitelist

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
listType Enumeration whitelist The type of list. Valid values are whitelist or blacklist.

Status 200 application/json

Response Body:

{
    "ipAddrs": [
        "192.169.19.29",
        "180.220.11.110"
    ],
    "domains": [
        "www.google.com",
        "www.facebook.com"
    ],
    "itemCount": 4,
    "remainingCount": 996
}
  1. Run List Configurations to retrieve a specific configId.

  2. For the type URL parameter, choose the appropriate value, either whitelist or blacklist.

  3. Make a GET request to /etp-config/v1/configs/{configId}/emergency-lists/{type}.

Update an Emergency List

Updates the properties and all items for a specific list by ip or domain.

PUT /etp-config/v1/configs/{configId}/emergency-lists/{listType}

Sample: /etp-config/v1/configs/342/emergency-lists/whitelist

Content-Type: application/json

Request Body:

{
    "ipAddrs": [
        "10.10.0.8"
    ],
    "domains": [
        "www.akamai.com"
    ]
}
Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
listType Enumeration whitelist The type of list. Valid values are whitelist or blacklist.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. For the type URL parameter, choose the appropriate value, either whitelist or blacklist.

  3. Run Get an Emergency List to retrieve an EmergencyList object.

  4. Modify the EmergencyList object.

  5. Make a PUT request to /etp-config/v1/configs/{configId}/emergency-lists/{type}.

List Honeypots

Returns a list of all Honeypots.

GET /etp-config/v1/configs/{configId}/honeypots

Sample: /etp-config/v1/configs/342/honeypots

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200 application/json

Response Body:

[
    {
        "id": 1,
        "name": "Honeypot 1",
        "description": "Akamai's Honeypot",
        "ipv4Addrs": [
            "196.168.1.1",
            "199.100.232.1"
        ],
        "ipv6Addrs": [
            "2019:D30::88/124",
            "2021:D32::88/124"
        ]
    }
]
  1. Run List Configurations to retrieve a specific configId.

  2. Make a GET request to /etp-config/v1/configs/{configId}/honeypots.

Create a Honeypot

Creates a new Honeypot.

POST /etp-config/v1/configs/{configId}/honeypots

Sample: /etp-config/v1/configs/342/honeypots

Content-Type: application/json

Request Body:

{
    "name": "Honeypot 1",
    "description": "Akamai's Honeypot",
    "ipv4Addrs": [
        "196.168.1.1",
        "199.100.232.1"
    ],
    "ipv6Addrs": [
        "2019:D30::88/124",
        "2021:D32::88/124"
    ]
}
Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200

Get a Honeypot

Returns the details of a specific Honeypot.

GET /etp-config/v1/configs/{configId}/honeypots/{honeypotId}

Sample: /etp-config/v1/configs/342/honeypots/1

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
honeypotId Integer 1 A unique identifier for a honeypot.

Status 200 application/json

Response Body:

{
    "id": 1,
    "name": "Example Honeypot",
    "description": "Example of a Honeypot configuration ",
    "ipv4Addrs": [
        "196.168.1.1",
        "199.100.232.1"
    ],
    "ipv6Addrs": [
        "2019:D30::88/124",
        "2021:D32::88/124"
    ]
}
  1. Run List Configurations to retrieve a specific configId.

  2. Run List Honeypots to retrieve a specific honeypotId.

  3. Make a GET request to /etp-config/v1/configs/{configId}/honeypots/{honeypotId}.

Update a Honeypot

Modifies a Honeypot’s features

PUT /etp-config/v1/configs/{configId}/honeypots/{honeypotId}

Sample: /etp-config/v1/configs/342/honeypots/1

Content-Type: application/json

Request Body:

{
    "name": "Honeypot 1",
    "description": "Akamai's Honeypot",
    "ipv4Addrs": [
        "196.168.1.1",
        "199.100.232.1"
    ],
    "ipv6Addrs": [
        "2019:D30::88/124",
        "2021:D32::88/124"
    ]
}
Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
honeypotId Integer 1 A unique identifier for a honeypot.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. Run List Honeypots to retrieve a specific honeypotId.

  3. Run Get a Honeypot to retrieve a Honeypot.

  4. Modify the Honeypot object.

  5. Make a PUT request to /etp-config/v1/configs/{configId}/honeypots/{honeypotId}.

Remove a Honeypot

Deletes a specific Honeypot.

DELETE /etp-config/v1/configs/{configId}/honeypots/{honeypotId}

Sample: /etp-config/v1/configs/342/honeypots/1

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
honeypotId Integer 1 A unique identifier for a honeypot.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. Run List Honeypots to retrieve a specific honeypotId.

  3. Make a DELETE request to /etp-config/v1/configs/{configId}/honeypots/{honeypotId}.

List Configuration Deployments

Returns all deployment history that the user has access to for the current ETP configuration.

GET /etp-config/v1/configs/{configId}/deployments

Sample: /etp-config/v1/configs/342/deployments

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200 application/json

Response Body:

[
    {
        "id": 101,
        "status": "COMPLETED",
        "message": "null",
        "startTime": "2016-08-31",
        "endTime": "2016-08-31",
        "deployedBy": "internal_user",
        "progressPct": 100
    }
]
  1. Run List Configurations to retrieve a specific configId.

  2. Make a GET request to /etp-config/v1/configs/{configId}/deployments.

Create a Configuration Deployment

Creates a new ETP configuration deployment.

POST /etp-config/v1/configs/{configId}/deployments

Sample: /etp-config/v1/configs/342/deployments

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200

Get a Configuration Deployment

Returns details of a specific ETP configuration deployment.

GET /etp-config/v1/configs/{configId}/deployments/{configDeploymentId}

Sample: /etp-config/v1/configs/342/deployments/101

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.
configDeploymentId Integer 101 A unique ID for the configuration deployment. Use this value for a configDeploymentId parameter in subsequent operations.

Status 200 application/json

Response Body:

{
    "id": 101,
    "status": "COMPLETED",
    "message": "null",
    "startTime": "2012-04-23T18:22:43.511Z",
    "endTime": "2012-04-23T18:25:43.511Z",
    "deployedBy": "internal_user",
    "progressPct": 100
}
  1. Run List Configurations to retrieve a specific configId.

  2. Run List Configuration Deployments to retrieve a specific configDeploymentId.

  3. Make a GET request to /etp-config/v1/configs/{configId}/deployments/{configDeploymentId}.

Get Recent Changes

Returns a list of all changes made since the last ETP configuration deployment.

GET /etp-config/v1/configs/{configId}/recentChanges

Sample: /etp-config/v1/configs/342/recentChanges

Parameter Type Sample Description
URL Parameters
configId Integer 342 A unique identifier for each configuration.

Status 200 application/json

Response Body:

{
    "created": [
        {
            "sites": [
                {
                    "id": 10,
                    "name": "Akamai Site 10"
                }
            ],
            "policies": [
                {
                    "id": 5,
                    "name": "Akamai Policy 5"
                }
            ],
            "honeypots": [
                {
                    "id": 5,
                    "name": "Akamai Honeypot 5"
                }
            ]
        }
    ],
    "deleted": [
        {
            "sites": [
                {
                    "id": 3,
                    "name": "Akamai Site 3"
                }
            ],
            "policies": [
                {
                    "id": 2,
                    "name": "Akamai Policy 2"
                }
            ],
            "honeypots": [
                {
                    "id": 8,
                    "name": "Akamai Honeypot 5"
                }
            ]
        }
    ],
    "modified": [
        {
            "sites": [
                {
                    "id": 1,
                    "name": "Akamai Site 1"
                }
            ],
            "policies": [
                {
                    "id": 4,
                    "name": "Akamai Policy 4"
                }
            ],
            "honeypots": [
                {
                    "id": 12,
                    "name": "Akamai Honeypot 12"
                }
            ],
            "whitelists": [
                {
                    "id": 1,
                    "name": "Akamai whitelists 1"
                }
            ],
            "blacklists": [
                {
                    "id": 1,
                    "name": "Akamai blacklists 1"
                }
            ]
        }
    ]
}
  1. Run List Configurations to retrieve a specific configId.

  2. Make a GET request to /etp-config/v1/configs/{configId}/recentChanges.

List Certificates

Returns a list of all available certificates.

GET /etp-config/v1/tls/customers/{configId}/certificates{?debug,include-certificate}

Sample: /etp-config/v1/tls/customers/1040/certificates?debug=false&include-certificate=false

Parameter Type Sample Description
URL Parameters
configId Integer 1040 A unique identifier for the configuration.
Optional Query Parameters
debug Boolean false When true, the response includes ISO–8601 timestamp fields for debugging.
include-certificate Boolean false When true, the response includes the certificate block.

Status 200 application/json

Response Body:

[
    {
        "certificateId": 5001,
        "fingerprint": "D1:AB:01:1C:A1:DE:CA:FC:0F:FE:E1:5F:EA:51:B1:E0",
        "issuedDate": "2016-10-11T00:15:38+0000",
        "expiredDate": "2019-10-11T00:15:38+0000",
        "status": "PENDING_ACTIVATION",
        "certificate": "-----BEGIN CERTIFICATE-----\nMIIDpjCCAo6gAwIBAgIIf8Ji8Dm81ko ... TXV0qe8SEF+C5n4=\n-----END CERTIFICATE-----\n",
        "caMode": "AKAMAI"
    },
    {
        "certificateId": "5002",
        "fingerprint": "BA:AD:CA:FE:F0:0D:AC:CE:55:1B:1E:15:AB:E1:1A:00",
        "issuedDate": "2015-10-11T00:15:38+0000",
        "expiredDate": "2018-10-11T00:15:38+0000",
        "status": "ACTIVATED",
        "certificate": "-----BEGIN CERTIFICATE-----\nMIIDpjCCAo6gAwIBAgIIf8Ji8Dm81ko ... TXV0qe8SEF+C5n4=\n-----END CERTIFICATE-----\n",
        "caMode": "CUSTOMER"
    }
]
  1. Run List Configurations to retrieve a specific configId.

  2. Optionally, set the debug query parameter to true to include ISO–8601 timestamp fields for debugging in the response.

  3. Optionally, set the include-certificate query parameter to true to include the certificate block in the response.

  4. Make a GET request to /etp-config/v1/tls/customers/{configId}/certificates{?debug,include-certificate}.

Create a New Certificate

Creates a new Certificate.

POST /etp-config/v1/tls/customers/{configId}/certificates

Sample: /etp-config/v1/tls/customers/1040/certificates

Content-Type: application/json

Request Body:

{
    "caMode": "AKAMAI"
}
Parameter Type Sample Description
URL Parameters
configId Integer 1040 A unique identifier for the configuration.

Status 201

  1. Run List Configurations to retrieve a specific configId.

  2. Create a Certificate object.

  3. Make a POST request to /etp-config/v1/tls/customers/{configId}/certificates.

Get a Certificate

Returns the details of the specified certificate.

GET /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}{?debug,include-certificate}

Sample: /etp-config/v1/tls/customers/1040/certificates/5001?debug=false&include-certificate=false

Parameter Type Sample Description
URL Parameters
configId Integer 1040 A unique identifier for the configuration.
certificateId Integer 5001 A unique identifier for the certificate.
Optional Query Parameters
debug Boolean false When true, the response includes ISO–8601 timestamp fields for debugging.
include-certificate Boolean false When true, the response includes the certificate block.

Status 200 application/json

Response Body:

{
    "certificateId": 5001,
    "fingerprint": "D1:AB:01:1C:A1:DE:CA:FC:0F:FE:E1:5F:EA:51:B1:E0",
    "issuedDate": "2016-10-11T00:15:38+0000",
    "expiredDate": "2019-10-11T00:15:38+0000",
    "status": "PENDING_ACTIVATION",
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDpjCCAo6gAwIBAgIIf8Ji8Dm81ko ... TXV0qe8SEF+C5n4=\n-----END CERTIFICATE-----\n",
    "caMode": "AKAMAI"
}
  1. Run List Configurations to retrieve a specific configId.

  2. Run List Certificates to retrieve a specific certificateId.

  3. Optionally, set the debug query parameter to true to include ISO–8601 timestamp fields for debugging in the response.

  4. Optionally, set the include-certificate query parameter to true to include the certificate block in the response.

  5. Make a GET request to /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}{?debug,include-certificate}.

Modify a Certificate

Updates the value of a certificate.

PUT /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}

Sample: /etp-config/v1/tls/customers/1040/certificates/5001

Content-Type: application/json

Request Body:

{
    "certificate": "-----BEGIN CERTIFICATE-----\nMIIDpjCCAo6gAwIBAgIIf8Ji8Dm81ko ... TXV0qe8SEF+C5n4=\n-----END CERTIFICATE-----\n"
}
Parameter Type Sample Description
URL Parameters
configId Integer 1040 A unique identifier for the configuration.
certificateId Integer 5001 A unique identifier for the certificate.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. Run List Certificates to retrieve a specific certificateId.

  3. Create a Certificate object.

  4. Make a PUT request to /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}.

Activate a Certificate

Transitions the certificate’s state from PENDING_ACTIVATION to ACTIVE.

POST /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}/op/activate

Sample: /etp-config/v1/tls/customers/1040/certificates/5001/op/activate

Parameter Type Sample Description
URL Parameters
configId Integer 1040 A unique identifier for the configuration.
certificateId Integer 5001 A unique identifier for the certificate.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. Run List Certificates to retrieve a specific certificateId.

  3. Make a POST request to /etp-config/v1/tls/customers/{customerId}/certificates/{certificateId}/op/activate.

Deactivate a Certificate

Transitions the certificate’s state from any of ACTIVATED, PENDING_ACTIVATION, PENDING_DOWNLOAD, PENDING_DISTRIBUTION and INCOMPLETE to DEACTIVATING.

POST /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}/op/deactivate

Sample: /etp-config/v1/tls/customers/1040/certificates/5001/op/deactivate

Parameter Type Sample Description
URL Parameters
configId Integer 1040 A unique identifier for the configuration.
certificateId Integer 5001 A unique identifier for the certificate.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. Run List Certificates to retrieve a specific certificateId.

  3. Make a POST request to /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}/op/deactivate.

Confirm Download

Transitions the certificate’s state from PENDING_DOWNLOAD to PENDING_ACTIVATION or INCOMPLETE.

POST /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}/op/confirm-download

Sample: /etp-config/v1/tls/customers/1040/certificates/5001/op/confirm-download

Parameter Type Sample Description
URL Parameters
configId Integer 1040 A unique identifier for the configuration.
certificateId Integer 5001 A unique identifier for the certificate.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. Run List Certificates to retrieve a specific certificateId.

  3. Make a POST request to /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}/op/confirm-download.

Confirm Distribute

Transitions the certificate’s state from PENDING_DISTRIBUTION to PENDING_ACTIVATION.

POST /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}/op/confirm-distribution

Sample: /etp-config/v1/tls/customers/1040/certificates/5001/op/confirm-distribution

Parameter Type Sample Description
URL Parameters
configId Integer 1040 A unique identifier for the configuration.
certificateId Integer 5001 A unique identifier for the certificate.

Status 200

  1. Run List Configurations to retrieve a specific configId.

  2. Run List Certificates to retrieve a specific certificateId.

  3. Make a POST request to /etp-config/v1/tls/customers/{configId}/certificates/{certificateId}/op/confirm-distribution.


Last modified: 4/10/2018