loading

Enterprise Threat Protector Configuration API v1

Manage policy settings to protect against events that compromise your security with ETP.

Learn more:


Overview

The Enterprise Threat Protector (ETP) Configuration API offers a programmatic OPEN interface to manage policy settings to protect against enterprise security and acceptable user policy related events. A distributed configuration encapsulates all the rules for how to process DNS requests for your enterprise.

Who should use this API

This API is for site administrators, project managers, and technical support providers who implement Enterprise Threat Protector (ETP) for your organization. It assumes that you have a working knowledge of ETP and how the configurable objects interact. If you are not familiar with these topics, see ETP Configuration Resources for more information.

Getting started

Before using the ETP Configuration API for the first time:

  • Contact your Akamai representative to enable it for your account.

  • Review the OPEN API Introduction on tools that Akamai provides.

  • Review OPEN API Provisioning to create your OPEN API access credentials and authorizations. As detailed in the OPEN API Identity Model, you then access the API using custom hostnames that looks like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

Object versioning

High-level objects such as Site, Policy, and CustomList use a timestamp for revision control. With each create, update, or delete, the object’s timestamp must be up to date. Requests fail with a 412 Precondition failed response if an older timestamp is provided in the request.

GET and POST operations pass the timestamp value in an Etag HTTP header. UPDATE and DELETE operations pass the timestamp in an If-Match HTTP header, with the correct ETag value.

TLS certificates

TLS termination is possible with an Akamai-issued certificate or a customer-provisioned certificate, so long as it is from an approved Akamai certificate authority (CA).

  • To use an Akamai CA, you need to trust the Akamai CA and use an Akamai generated certificate. You also need to install the Akamai generated certificate manually or with the use of an MDM solution on the client device.

  • To use a customer-owned certificate, you need to generate a certificate signing request (CSR) using the Enterprise Threat Protector Application, sign it, and upload the signed certificate using the 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[] 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.

Data

This section provides you with the data model for the ETP Config API.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

Member is required to be present, regardless of whether its value is empty or null.
Member is optional, and may be omitted in some cases.

Site

Specifies IP addresses and CIDR blocks of a region or geographic area in your network to compare incoming requests against an assigned policy.

Download schema: site-retrieve-specific.json

Sample GET response:

{
    "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"
    }
}

Site members

Member Type Required Description
description String A description of the site configuration that you provide.
exitPoints Site.exitPoints[] Encapsulates data for Site exit points.
id Integer A unique identifier for each site. Use this value for a siteId parameter in subsequent operations.
name String The name of the site configuration.
policyId Integer The unique ID of the related policy.
policyInfo Site.policyInfo Specifies the related policy ETP applies to incoming DNS requests.
Site.exitPoints[]: Encapsulates data for Site exit points.
addrType Enumeration The type of internet protocol address, either ADDR_TYPE_IPV4 or ADDR_TYPE_IPV6.
ipAddr String The IP address or CIDR block for your company branch or headquarters used to match a policy to a request.
Site.policyInfo: Specifies the related policy ETP applies to incoming DNS requests.
id Integer Read-only. The unique ID of the related policy.
name String The name of the related policy.

Policy

This object encapsulates the security policy to assign to a site. You can configure the Accepted Use Policy (AUP) and set responses for known and suspected threats under specified categories.

Download schema: policy-retrieve-specific.json

Sample GET response:

{
    "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
        }
    ]
}

Policy members

Member Type Required Description
aupSettings Policy.aupSettings[] Contains the AUP settings.
basicSettings Policy.basicSettings Contains the basic policy settings.
description String A description of the policy that you provide.
id Integer A unique identifier for each policy. Use this value for a policyId parameter in subsequent operations.
name String The name of the policy.
securitySettings Policy.securitySettings[] Contains the policy security settings.
sites Array Encapsulates associated site IDs.
sitesInfo Policy.sitesInfo[] Encapsulates data of an associated site.
Policy.aupSettings[]: Contains the AUP settings.
categoryId Integer A unique identifier for the category.
categoryInfo Policy.aupSettings[].categoryInfo Encapsulates data for a category.
responseId Integer A unique identifier for the response.
responseInfo Policy.aupSettings[].responseInfo Encapsulates data for the response.
Policy.aupSettings[].categoryInfo: Encapsulates data for a category.
id Integer Read-only. A unique identifier for the category.
name String The name of the category.
Policy.aupSettings[].responseInfo: Encapsulates data for the response.
id Integer Read-only. A unique identifier for the response.
name String The name of the response.
Policy.basicSettings: Contains the basic policy settings.
edns0ecs Boolean When enabled, optimizes CDN traffic using the EDNS-Client-Subnet extension.
Policy.securitySettings[]: Contains the policy security settings.
confirmedResponseId Integer A unique identifier for the confirmed response.
confirmedResponseInfo Policy.securitySettings[].confirmedResponseInfo Encapsulates data about the confirmed response.
listId Integer A unique identifier for the list.
listInfo Policy.securitySettings[].listInfo Encapsulates data about the list.
shouldNotifyConfirmed Boolean Send alert on confirmed list hit.
shouldNotifySuspected Boolean Send alert on suspected list hit.
suspectedResponseId Integer A unique identifier for the suspected response.
suspectedResponseInfo Policy.securitySettings[].suspectedResponseInfo Encapsulates data about the suspected response.
Policy.securitySettings[].confirmedResponseInfo: Encapsulates data about the confirmed response.
id Integer Read-only. A unique identifier for the confirmed response.
name String The name of the confirmed response.
Policy.securitySettings[].listInfo: Encapsulates data about the list.
id Integer Read-only. A unique identifier for the list.
name String The name of the list.
Policy.securitySettings[].suspectedResponseInfo: Encapsulates data about the suspected response.
id Integer Read-only. A unique identifier for the suspected response.
name String The name of the suspected response.
Policy.sitesInfo[]: Encapsulates data of an associated site.
id Integer Read-only. The unique identifier for the site.
name String The name of the site.

CustomList

This object is a custom a security list of domains and IP addresses, with a set confidence level for each.

Download schema: list-retrieve-specific.json

Sample GET response:

{
    "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
}

CustomList members

Member Type Required Description
description String A description of the list that you provide.
id Integer A unique identifier for each list. Use this value for a listId parameter in subsequent operations.
itemCount Integer The number of entries in a list.
knownCounts CustomList.knownCounts Encapsulates data of known counts.
name String The name of the list.
remainingCount Integer The number of remaining entries for all lists globally.
securityCategoryId Integer A unique identifier for the security category.
securityCategoryInfo CustomList.securityCategoryInfo Encapsulates data about the security category.
suspectedCounts CustomList.suspectedCounts The count of suspected domain entries in the list.
CustomList.knownCounts: Encapsulates data of known counts.
domains Integer The count of known domain entries in the list.
ips Integer The count of known IP addresses in the list.
CustomList.securityCategoryInfo: Encapsulates data about the security category.
id Integer A unique identifier for the security category.
name String The name of the security category.
CustomList.suspectedCounts: The count of suspected domain entries in the list.
domains Integer The count of suspected domains in the list.
ips Integer The count of suspected IP addresses in the list.

EmergencyList

This object contains a whitelist or blacklist of domains and IP addresses to allow or block on your domain. These lists are applied globally across site configurations and override individual policy settings.

Download schema: emergency-list-retrieve-specific.json

Sample GET response:

{
    "ipAddrs": [
        "192.169.19.29",
        "180.220.11.110"
    ],
    "domains": [
        "www.google.com",
        "www.facebook.com"
    ],
    "itemCount": 4,
    "remainingCount": 996
}

EmergencyList members

Member Type Required Description
domains Array Array of data entries. Each element corresponds to a domain.
ipAddrs Array Array of data entries. Each element corresponds to an IP address.
itemCount Integer The total count of entries in the list.
remainingCount Integer Remaining count of entries that you can add to the list.

ListItem

This object provides details for a list entry.

Download schema: list-set-items-content.json

Sample GET response:

[
    {
        "type": "LIST_TYPE_IP",
        "value": "192.168.100.100",
        "confidenceLevelId": 1
    }
]

ListItem members

Member Type Required Description
confidenceLevelId Enumeration An identifier that corresponds to the confidence level of the list item. A value of 1 signifies a suspected item, while a value of 2 signifies a known item.
type Enumeration Specifies whether the list item is an IP address (LIST_TYPE_IP) or domain (LIST_TYPE_DOMAIN).
value String The IP address or domain of the list item.

ListPatch

This object contains items to add or delete when performing a patch operation on a list.

Download schema: list-modify-items-content.json

Sample GET response:

{
    "delete": [
        "192.160.100.100",
        "220.10.100.11"
    ],
    "add": [
        {
            "type": "LIST_TYPE_IP",
            "value": "115.65.10.134",
            "confidenceLevelId": 2
        }
    ]
}

ListPatch members

Member Type Required Description
add ListPatch.add[] Contains details of the list item to add in the patch operation.
delete Array An array of Ip Addresses and Domains to delete in the patch operation.
ListPatch.add[]: Contains details of the list item to add in the patch operation.
confidenceLevelId Enumeration An identifier that corresponds to the confidence level of the list item. A value of 1 signifies a suspected item, while a value of 2 signifies a known item.
type Enumeration Specifies whether the list item is an IP address (LIST_TYPE_IP) or domain (LIST_TYPE_DOMAIN).
value String The IP address or domain of the list item.

ListQuota

This object returns the global count of entries in all lists and the remaining entries available to provision.

Download schema: list-get-global-quota.json

Sample GET response:

{
    "count": 1000,
    "remainingCount": 990
}

ListQuota members

Member Type Required Description
count Number The total number of list items currently in your configuration.
remainingCount Number The remaining number of list items that you can add to your configuration.

Honeypot

This object specifies a honeypot for receiving and monitoring malicious requests. Honeypots are monitored resources within a network that provide secure responses to the request in order to gain insight into an attack and the methods they use.

Download schema: honeypot-retrieve-specific.json

Sample GET response:

{
    "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"
    ]
}

Honeypot members

Member Type Required Description
description String The description of the Honeypot.
id Integer A unique identifier for each honeypot. Use this value for a honeypotId parameter in subsequent operations.
ipv4Addrs Array An array of data entries. Each element corresponds to an IPv4 address of a target device.
ipv6Addrs Array An array of data entries. Each element corresponds to an IPv6 address of a target device.
name String The name of the Honeypot.

ListDeployment

Encapsulates data describing the status and details of a list configuration deployment.

Download schema: list-deployment-retrieve-specific.json

Sample GET response:

{
    "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"
}

ListDeployment members

Member Type Required Description
deployedBy String The user who created the deployment.
endTime String Read-only. The end time of the deployment in ISO 8601 format.
id Integer A unique identifier for each list deployment. Use this value for a listDeploymentId parameter in subsequent operations.
message String The status message, in cases where failure of deployment occurs.
startTime String Read-only. The start time of the deployment in ISO 8601 format.
status Enumeration The status of list deployment, either PENDING, RUNNING, COMPLETED, or FAILED.

ConfigurationDeployment

Encapsulates data describing the status and details of an ETP configuration deployment.

Download schema: etp-configuration-deployment-retrieve-specific.json

Sample GET response:

{
    "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
}

ConfigurationDeployment members

Member Type Required Description
deployedBy String The user who created the deployment.
endTime String Read-only. The end time of the deployment in ISO 8601 format.
id Integer A unique identifier for each configuration deployment. Use this value for a configDeploymentId parameter in subsequent operations.
message String The status message, in cases where failure of deployment occurs.
progressPct Number The percentage of deployment progress.
startTime String Read-only. The start time of the deployment in ISO 8601 format.
status Enumeration The status of list deployment, either PENDING, RUNNING, COMPLETED, or FAILED.

DnsConfiguration

Contains 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.

Download schema: dns-configuration.json

Sample GET response:

{
    "ipv4Addrs": {
        "primary": "192.168.10.10",
        "secondary": "192.160.10.20"
    },
    "ipv6Addrs": {
        "primary": "2021:D32::88/124",
        "secondary": "2021:D32::89/124"
    }
}

DnsConfiguration members

Member Type Required Description
ipv4Addrs DnsConfiguration.ipv4Addrs Encapsulates data about IPv4 DNS configuration.
ipv6Addrs DnsConfiguration.ipv6Addrs Encapsulates data about IPv6 DNS configuration.
DnsConfiguration.ipv4Addrs: Encapsulates data about IPv4 DNS configuration.
primary String Primary IPv4 Address.
secondary String Secondary IPv4 Address.
DnsConfiguration.ipv6Addrs: Encapsulates data about IPv6 DNS configuration.
primary String Primary IPv6 address.
secondary String Secondary IPv6 address.

Certificate

Encapsulates data about a TLS certificate.

Download schema: certificate.json

Sample GET response:

{
    "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"
}

Certificate members

Member Type Required Description
caMode Enumeration Mode of the certificate, either CUSTOMER or AKAMAI.
certificate String Value of the certificate in PEM format: ASCII, base64-encoded text starting with -----BEGIN CERTIFICATE----- and ending with -----END CERTIFICATE-----.
certificateId Number Read-only. A unique identifier for each certificate.
certificateRequest String Value for the certificate signing request (CSR): ASCII, base64-encoded text starting with -----BEGIN CERTIFICATE REQUEST----- and ending with -----END CERTIFICATE REQUEST-----.
createdBy String Read-only. Name of the user who created this Certificate object.
createdDate String Read-only. ISO–8601 timestamp marking when this Certificate object was created.
expiredDate String Read-only. ISO–8601 timestamp marking when the certificate is set to expire.
fingerprint String Read-only. The certificate’s hexadecimal fingerprint.
issuedDate String Read-only. ISO–8601 timestamp marking when the certificate was issued.
modifiedBy String Read-only. Name of the user who most recently modified this Certificate object. If the object was not modified since first being created, the value matches createdBy.
modifiedDate String Read-only. ISO–8601 timestamp marking when this Certificate object was last modified. If the object was not modified since first being created, the value matches createdDate.
status Enumeration Read-only. Certificate deployment status, either CREATING, INCOMPLETE, UPDATING, PENDING_DOWNLOAD, PENDING_DISTRIBUTION, PENDING_ACTIVATION, ACTIVATING, ACTIVATED, DEACTIVATING, DEACTIVATED, or EXPIRED.

Errors

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

Error responses

EdgeGrid responds with HTTP Problem error objects that provide details useful for debugging. For example:

{
    "type": "https://problems.omni.akamaiapis.net/http/forbidden",
    "title": "Forbidden",
    "detail": "Insufficient permissions. Code-01",
    "status": 403,
    "instance": "3e3f11da-e205-409a-be77-24e459f29fa8"
}

HTTP status codes

The API produces the following set of HTTP status codes for both success and failure scenarios:

Code Description
200 The operation was successful.
403 Access is forbidden.
404 Resource not found.
406 Not acceptable.
409 Conflict with current state of resource.
412 An Etag or If-Match header does not match, indicating the content has been modified. See Object Versioning for more information.

Last modified: 4/10/2018