loading

Akamai Cloud Embed API v2

Manages Akamai Cloud Embed (ACE) and Integrated Cloud Acceleration (ICA).

Learn more:


Overview

The Akamai Cloud Embed API lets you, as an Akamai cloud partner, provide Content Delivery Network (CDN) features to your cloud customers, who are also known as subcustomers.

With this API you can configure CDN features per domain and give your subcustomers the ability to purchase, configure, and monitor Akamai’s CDN services directly through your portal.

In most cases, once you create one or more base configurations to support your business needs, you can use this API to support hundreds of thousands of subcustomers per base configuration.

In order to use this API and its core delivery, download, and video streaming capabilities, you need to add Akamai Cloud Embed to your contract. To use the acceleration features, you have to sign up for Integrated Cloud Accelerator (ICA).

NOTE: Akamai Cloud Embed used to be called Wholesale Delivery.

Getting started

To configure this API for the first time:

  • Contact Akamai to enable Akamai Cloud Embed for your account. If you want acceleration features, you also need to add ICA.

  • If your subcustomers support both HTTP and HTTPS traffic, contact Akamai to create a secure Akamai Cloud Embed base configuration and provision the necessary certificates. This is the preferred configuration for Akamai Cloud Embed. However, you can create this configuration yourself, if desired using the Property manager Editor in the Luna Control Center.

  • If your subcustomers only support HTTP traffic, contact Akamai to request a Multi-Domain Edge Hostname and create an InstantConfig property. A Multi-Domain Edge Hostname lets you use a single hostname to represent multiple web assets.

  • Create an origin hostname. You need to create a hostname to identify a default origin server that is separate from your subcustomer cloud origins.

  • Create an error page. Once you create a hostname to identify a default origin server, configure this default origin to serve an error page when a subcustomer’s domain is not configured correctly.

  • Determine the method to use to create subcustomer IDs. Each customer in your billing system who uses your Akamai Cloud Embed implementation needs this ID. You can use any method to generate IDs as long as the IDs are unique. All traffic for a particular subcustomer is rolled up by this ID for billing.

  • Add the Sub-Customer Enablement behavior to your base configuration via Property Manager in Luna. Once added, you need to decide which Akamai Cloud Embed features you want to offer to your subcustomers, and enable them accordingly. Your decisions determine the structure of your policy JSON going forward. (Your policy JSON is made up of rules that include both match criteria and behaviors for use with that specific subcustomer.)

  • If you are using Integrated Cloud Accelerator, enable the Dynamic Web Content option in the Sub-Customer Enablement behavior.

  • If you’re using a non-secure (HTTP), Multi-Domain Edge Hostname, enable the InstantConfig behavior in your base configuration via Property Manager. InstantConfig lets you associate multiple web assets to a single property without adding each hostname to the base configuration.

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

  • To enable this API, choose the API service named Wholesale Delivery, and set the access level to READ-WRITE.

Interactions with other Akamai APIs

You can use the Akamai Cloud Embed API in conjunction with the following Akamai APIs:

  • Billing Center. This provides access to CSV-based contract usage data for accounts you can access. We provide separate reports for Akamai Cloud Embed and ICA, per billing period. The Akamai Cloud Embed report lists subcustomer usage (hits and bytes) by geography. The ICA report contains billing data for subcustomers that used ICA, without reference to geography.

  • Media Reports. This lets you retrieve usage and quality metrics for Akamai Cloud Embed. It does not include billing data. Currently, this API combines Akamai Cloud Embed and ICA data: If a given operation served both Akamai Cloud Embed and ICA traffic during the selected time period, the report does not differentiate between the two. In addition, this API also reports metrics for the following Media Delivery products: Adaptive Media Delivery, Download Delivery, RTMP Media Delivery, and Object Delivery.

  • Property Manager API. You can use the Property Manager API to create and update a base configuration for Akamai Cloud Embed. However, you typically only need one base configuration. For ease of use, we recommend that you use Property Manager via the Luna Control Center.

Concepts

  • Cloud partners. Akamai resellers or partners who provide delivery services to their customers. You, as a user of this API, are a cloud partner, also referred to simply as “partner” throughout this documentation.

  • Subcustomers. A cloud partner’s customers are subcustomers. Akamai does not assign individual Content Provider (CP) codes to subcustomers even though their traffic is sent over the Akamai platform. As a Cloud Partner you have access to usage detail reports for each of your subcustomers, based on the subcustomer IDs you provide Akamai.

  • Subcustomer ID. This is a unique ID for each subcustomer within your own billing systems. All traffic for a particular subcustomer is rolled up by this ID for billing purposes.

  • Base configuration. An Akamai delivery configuration that includes all of the common rules for processing end-user requests. You use the Property Manager API or GUI application to configure properties used for both Akamai Cloud Embed and ICA.

  • Sub-Customer Enablement behavior. In Property Manager, the subCustomer behavior controls which individual Akamai Cloud Embed and ICA features are available to handle your subcustomers’ traffic. You can set up this behavior to provide access to all available features, or you can select a subset of features to define different classes of service.

  • Content Characteristics-Dynamic Web Content behavior. Include this behavior if you only want to enable specific ICA optimizations for your subcustomers.

  • InstantConfig behavior. If your subcustomers only send HTTP traffic, you have to add the instantConfig behavior to your property. This behavior, also known as Multi-Domain Configuration, lets you to associate multiple web assets to a single property without adding each hostname separately. It applies property settings to all incoming hostnames based on a DNS lookup.

  • Policy. Policies determine how Akamai edge servers handle a given subcustomer’s requests. A single policy is bound to a hostname. Your policy JSON is made up of rules, which contain both match criteria and behaviors. When an incoming request meets the match criteria in a rule, it triggers the behaviors listed in that rule. Rules must be unique within a policy: they can’t have identical sets of matches. A policy can also contain up to 100 behaviors.

  • Policy rules. Rules include both match criteria and behaviors. When an incoming request meets the match criteria in a rule, it triggers the behaviors listed in that rule. Within a rule you can use each match type and each behavior once. Also, no one rule can contain both a whitelist and blacklist behavior of a given type. For example, you can add an IP whitelist and a referrer blacklist to a rule, but you can’t have both an IP whitelist and IP blacklist in the same rule. Rules are applied from top to bottom and should be listed from least restrictive to most restrictive. For example, you would list a match on url-wildcard value /* first because it would apply to all requests, where /images/* would only apply to a subset of requests.

  • Policy matches. Within a rule, a match defines which subcustomer requests receive the behaviors within the rule. All match conditions for a rule must evaluate to true in order for the behaviors to apply. When constructing the matches array in a rule, the type of data you enter depends on the type of match. For example, if you use the query string match, you have to enter the exact string and keep case sensitivity in mind. If you use the url-scheme match, you enter either HTTP or HTTPS. Within a match, you cannot repeat entries in the value string.

  • Policy behaviors. Like Property Manager, the Akamai Cloud Embed API uses behaviors to encapsulate customizable settings. Behaviors are a part of a policy’s rules. A rule can have many behaviors or only one. For the Akamai Cloud Embed API, you group rules into policies. You can have a maximum of 100 behaviors in a subcustomer policy. Policies exceeding 100 behaviors are rejected upon submission. Within a behavior, you cannot repeat entries in the value string.

Resources

The Akamai Cloud Embed API allows you as our “partner” to manage the Content Delivery Network (CDN) features available to your customers (“subcustomers”) when using Akamai Cloud Embed or Integrated Cloud Acceleration (ICA). With this API, you can create and manage subcustomer policies and IDs.

Follow this basic workflow to create a subcustomer ID and policy:

  1. Complete the prerequisites in Getting started.

  2. If not completed already, use Property Manager in Luna to create a “base configuration,” and ensure that the Sub-Customer Enablement behavior is configured to meet your needs. This configuration and behavior determine baseline settings for use. (It serves as a “limiter.” It states what settings can and can’t be used for all subcustomers associated with the configuration).

  3. Run the Add a new subcustomer operation to apply and register a “subcustomer ID” for each of your customers.

  4. Run the Create or update a policy operation for each subcustomer ID you need to add to your base configuration. Setup the policy with individual rules and behaviors that you want applied when a request is received for that subcustomer’s content.

  5. Test the end-to-end CDN functionality with each subcustomer. You should use a test domain to validate both the functionality and the configuration.

  6. For the final step to go live, change applicable DNS to switch Cloud Partner websites to the Akamai platform.

API summary

Download the RAML descriptors for this API.

Operation Method Endpoint
Subcustomer  
List all subcustomers GET /partner-api/v2/network/{network}/properties/{propertyId}/customers
Get a subcustomer GET /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}
Add a new subcustomer PUT /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}
Remove a subcustomer DELETE /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}
Property  
List all sub-properties for a base configuration GET /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties
List all subcustomer domains GET /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}/sub-properties
Policy  
Get a policy GET /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy
Create or update a policy PUT /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy
Delete a policy DELETE /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy
Get policy history GET /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy/history

List all subcustomers

Returns a list of all subcustomers associated with the selected base configuration (propertyId).

GET /partner-api/v2/network/{network}/properties/{propertyId}/customers

Sample: /partner-api/v2/network/production/properties/12345/customers

Parameter Type Sample Description
URL parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId Integer 12345 The ID number of the base configuration file. This number is automatically generated when the configuration is created.

Status 200 application/json

Response Body:

[
    {
        "customerID": "abc-123",
        "geo": "FR",
        "subPropertyIDs": [
            "www.example.com",
            "www.example.biz",
            "www.example.net",
            "www.example.co.uk"
        ]
    }
]
  1. Determine which network you want to retrieve information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId associated with the applicable base configuration.

  3. Make a GET request to /partner-api/v2/network/{network}/properties/{propertyId}/customers.

  4. Review the list of subcustomers and their geographies returned in the SubCustomer response.

Get a subcustomer

Returns policy information for the selected subcustomer and activation network.

GET /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}

Sample: /partner-api/v2/network/production/properties/12345/customers/SC12345

Parameter Type Sample Description
URL parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId Integer 12345 The ID number of the base configuration file. This number is automatically generated when the configuration is created.
subcustomerId String SC12345 The unique ID of the subcustomer. Your organization assigns this value.

Status 200 application/json

Response Body:

{
    "geo": "FR"
}
  1. Determine which network you want to retrieve information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId associated with the applicable base configuration.

  3. Run the List customers operation and store the customer value, which corresponds to the subcustomerId URL parameter.

  4. Make a GET request to /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}.

Add a new subcustomer

Add a new subcustomer ID to the selected base configuration (propertyId).

PUT /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}

Sample: /partner-api/v2/network/production/properties/12345/customers/SC12345

Content-Type: application/json

Request Body:

{
    "geo": "FR"
}
Parameter Type Sample Description
URL parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId Integer 12345 The ID number of the base configuration file. This number is automatically generated when the configuration is created.
subcustomerId String SC12345 The unique ID of the subcustomer. Your organization assigns this value.

Status 200 application/json

Response Body:

{
    "geo": "FR"
}
  1. Determine which network you want to retrieve information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId associated with the applicable base configuration.

  3. You need to provide a unique ID for the subcustomer (subcustomerId). As the cloud partner, it’s up to you to determine a method to create these IDs and associate them with each subcustomer. The ID can contain up to 50 alphanumeric, dot or dash characters.

  4. Make a PUT request to /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}. You also need to include the subcustomer’s geo (geographic region) in a PUT request body. Use the valid two letter country designation (for example, US for United States or BR for Brazil).

  5. Verify that the geo value returned in the response is accurate for the subcustomer you added.

Remove a subcustomer

Remove a specific subcustomer using its unique subcustomerId

DELETE /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}

Sample: /partner-api/v2/network/production/properties/12345/customers/SC12345

Parameter Type Sample Description
URL parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId Integer 12345 The ID number of the base configuration file. This number is automatically generated when the configuration is created.
subcustomerId String SC12345 The unique ID of the subcustomer. Your organization assigns this value.

Status 200 application/json

Response Body:

{
    "description": "The subcustomer for property_id '251922' and subcustomer_id '0004-propertyfolks' was successfully deleted.",
    "message": "Successfully deleted"
}
  1. Determine which network you want to retrieve information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId associated with the applicable base configuration.

  3. Run the List all subcustomers operation and store the customerID value, that applies to the applicable subcustomer. This is used as the subcustomerId URL parameter for this operation.

  4. Make a DELETE request to /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}.

  5. Review the Message response returned to verify the deletion was successful.

List all sub-properties for a base configuration

Returns all of the domains (subPropertyID values) for subcustomers associated with a selected base configuration (propertyId) and activation network.

GET /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties

Sample: /partner-api/v2/network/production/properties/12345/sub-properties

Parameter Type Sample Description
URL parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String 12345 The ID number of the base configuration file. This number is automatically generated when the configuration is created.

Status 200 application/json

Response Body:

[
    {
        "subPropertyID": "www.example.com",
        "customerID": "abc-123"
    },
    {
        "subPropertyID": "www.example.biz",
        "customerID": "abc-123"
    },
    {
        "subPropertyID": "www.example.com.net",
        "customerID": "def-456"
    },
    {
        "subPropertyID": "www.example.com.co.uk",
        "customerID": "def-456"
    }
]
  1. Determine which network you want to retrieve information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId associated with the applicable base configuration.

  3. Make a GET request to /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties.

List all subcustomer domains

Returns domain-specific information for the selected subcustomer domain (subPropertyID) and activation network.

GET /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}/sub-properties

Sample: /partner-api/v2/network/production/properties/12345/customers/SC12345/sub-properties

Parameter Type Sample Description
URL parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String 12345 The ID number of the base configuration file. This number is automatically generated when the configuration is created.
subcustomerId String SC12345 The unique ID of the subcustomer. Your organization assigns this value.

Status 200 application/json

Response Body:

[
    {
        "customerID": "abc-123",
        "geo": "FR",
        "subPropertyIDs": [
            "www.example.com",
            "www.example.biz",
            "www.example.net",
            "www.example.co.uk"
        ]
    }
]
  1. Determine which network you want to retrieve information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId associated with the applicable base configuration.

  3. Run the List customers operation and store the customer value, which corresponds to the subcustomerId URL parameter.

  4. Make a GET request to /partner-api/v2/network/{network}/properties/{propertyId}/customers/{subcustomerId}/sub-properties.

Get a policy

Returns the policy for the selected subcustomer domain, base configuration (propertyId), and activation network.

GET /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy

Sample: /partner-api/v2/network/production/properties/12345/sub-properties/www.example.com/policy

Parameter Type Sample Description
URL parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String 12345 The ID number of the base configuration file. This number is automatically generated when the configuration is created.
domainName String www.example.com The name of the subcustomer’s domain.

Status 200 application/json

Response Body:

{
    "rules": [
        {
            "matches": [
                {
                    "name": "http-method",
                    "value": "GET"
                }
            ],
            "behaviors": [
                {
                    "params": {
                        "originBasePath": "-",
                        "cacheKeyValue": "-",
                        "digitalProperty": "www.example.com",
                        "cacheKeyType": "origin",
                        "httpPort": 80,
                        "hostHeaderValue": "-",
                        "originDomain": "www.example.com",
                        "hostHeaderType": "origin"
                    },
                    "name": "origin",
                    "value": "-"
                },
                {
                    "type": "fixed",
                    "name": "caching",
                    "value": "1m"
                }
            ]
        }
    ]
}
  1. Determine which network you want to retrieve information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId associated with the applicable base configuration.

  3. Run the List all sub-properties for a base configuration operation and store the value from the subPropertyIDs array, that corresponds to the appropriate subcustomer’s customerID. This is used as the domainName URL parameter for this operation.

  4. Make a GET request to /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy.

  5. Review the rule information returned in the Policy response.

Create or update a policy

Create a new subcustomer policy or update an existing one.

PUT /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy

Sample: /partner-api/v2/network/production/properties/12345/sub-properties/www.example.com/policy

Headers:

X-Customer-ID: 100-example.com
X-Custom-Metadata: 100

Content-Type: application/json

Request Body:

{
    "rules": [
        {
            "matches": [
                {
                    "name": "http-method",
                    "value": "GET"
                }
            ],
            "behaviors": [
                {
                    "params": {
                        "originBasePath": "-",
                        "cacheKeyValue": "-",
                        "digitalProperty": "www.example.com",
                        "cacheKeyType": "origin",
                        "httpPort": 80,
                        "hostHeaderValue": "-",
                        "originDomain": "www.example.com",
                        "hostHeaderType": "origin"
                    },
                    "name": "origin",
                    "value": "-"
                },
                {
                    "type": "fixed",
                    "name": "caching",
                    "value": "1m"
                }
            ]
        }
    ]
}
Parameter Type Sample Description
URL parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String 12345 The ID number of the base configuration file. This number is automatically generated when the configuration is created.
domainName String www.example.com The name of the subcustomer’s domain.

Status 200 application/json

Response Body:

{
    "rules": [
        {
            "matches": [
                {
                    "name": "http-method",
                    "value": "GET"
                }
            ],
            "behaviors": [
                {
                    "params": {
                        "originBasePath": "-",
                        "cacheKeyValue": "-",
                        "digitalProperty": "www.example.com",
                        "cacheKeyType": "origin",
                        "httpPort": 80,
                        "hostHeaderValue": "-",
                        "originDomain": "www.example.com",
                        "hostHeaderType": "origin"
                    },
                    "name": "origin",
                    "value": "-"
                },
                {
                    "type": "fixed",
                    "name": "caching",
                    "value": "1m"
                }
            ]
        }
    ]
}
  1. Determine which network you want to retrieve information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId associated with the applicable base configuration.

  3. Run the List all sub-properties for a base configuration operation and store the value from the subPropertyIDs array, that corresponds to the appropriate subcustomer’s customerID. This is used as the domainName URL parameter for this operation.

  4. Include a valid, registered subcustomer ID as the X-Customer-ID header. You can also optionally specify a string up to 50 characters in length to serve as the X-Custom-Metadata header, for use in billing and reporting.

  5. Make a PUT request to /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy. Include a properly formatted request body with rules that consist of proper match criteria, and the behaviors that should be applied when a request for the subcustomer’s content meets that criteria.

  6. Review the information returned in the Policy response.

Delete a policy

Deletes the currently active policy file for the selected subcustomer domain and activation network.

DELETE /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy

Sample: /partner-api/v2/network/production/properties/12345/sub-properties/www.example.com/policy

Parameter Type Sample Description
URL parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String 12345 The ID number of the base configuration file. This number is automatically generated when the configuration is created.
domainName String www.example.com The name of the subcustomer’s domain.

Status 200 application/json

Response Body:

{
    "message": "Successfully deleted",
    "description": "The policy was successfully deleted.",
    "successInstanceId": "a123bcedfg45"
}
  1. Determine which network you want to retrieve information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId associated with the applicable base configuration.

  3. Run the List all sub-properties for a base configuration operation and store the value from the subPropertyIDs array, that corresponds to the appropriate subcustomer’s customerID. This is used as the domainName URL parameter for this operation.

  4. Make a DELETE request to /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy.

  5. Review the Message response returned to verify the deletion was successful.

Get policy history

Returns policy change information for the selected subcustomer domain, base configuration (propertyId), and activation network.

GET /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy/history

Sample: /partner-api/v2/network/production/properties/12345/sub-properties/www.example.com/policy/history

Parameter Type Sample Description
URL parameters
network Enumeration production The network for the policy, either staging for the testing network, or production for the live network.
propertyId String 12345 The ID number of the base configuration file. This number is automatically generated when the configuration is created.
domainName String www.example.com The name of the subcustomer’s domain.

Status 200 application/json

Response Body:

[
    {
        "papi_version": "1.3",
        "policy": {
            "rules": [
                {
                    "behaviors": [
                        {
                            "name": "origin",
                            "params": {
                                "cacheKeyType": "digital_property",
                                "cacheKeyValue": "-",
                                "digitalProperty": "sportsguys.wsdtest.akalab.com",
                                "hostHeaderType": "digital_property",
                                "hostHeaderValue": "-",
                                "originDomain": "sportsguys.wsdtest.akalab.com.s3-website-us-west-1.amazonaws.com"
                            },
                            "value": "-"
                        }
                    ],
                    "matches": [
                        {
                            "name": "http-method",
                            "value": "GET"
                        }
                    ]
                },
                {
                    "behaviors": [
                        {
                            "name": "caching",
                            "type": "fixed",
                            "value": "1h"
                        }
                    ],
                    "matches": [
                        {
                            "name": "url-extension",
                            "value": "jpg"
                        }
                    ]
                },
                {
                    "behaviors": [
                        {
                            "name": "caching",
                            "type": "fixed",
                            "value": "1d"
                        }
                    ],
                    "matches": [
                        {
                            "name": "url-extension",
                            "value": "mp4"
                        }
                    ]
                }
            ]
        },
        "update_timestamp": 1440722458,
        "version": 1
    },
    {
        "papi_version": "1.3",
        "policy": {
            "rules": [
                {
                    "behaviors": [
                        {
                            "name": "origin",
                            "params": {
                                "cacheKeyType": "digital_property",
                                "cacheKeyValue": "-",
                                "digitalProperty": "www.example.akalab.com",
                                "hostHeaderType": "digital_property",
                                "hostHeaderValue": "-",
                                "originDomain": "www.example.com"
                            },
                            "value": "-"
                        }
                    ],
                    "matches": [
                        {
                            "name": "http-method",
                            "value": "GET"
                        }
                    ]
                },
                {
                    "behaviors": [
                        {
                            "name": "caching",
                            "type": "fixed",
                            "value": "1h"
                        }
                    ],
                    "matches": [
                        {
                            "name": "url-extension",
                            "value": "jpg"
                        }
                    ]
                },
                {
                    "behaviors": [
                        {
                            "name": "caching",
                            "type": "fixed",
                            "value": "1d"
                        }
                    ],
                    "matches": [
                        {
                            "name": "url-extension",
                            "value": "mp4"
                        }
                    ]
                }
            ]
        },
        "update_timestamp": 1440722462,
        "version": 2
    }
]
  1. Determine which network you want to retrieve information from. You can choose staging (testing) or production (live).

  2. Contact your Akamai account representative for the propertyId associated with the applicable base configuration.

  3. Run the List all sub-properties for a property ID operation and store the appropriate value from the subPropertyIDs array, which corresponds to the domainName URL parameter.

  4. Make a GET request to /partner-api/v2/network/{network}/properties/{propertyId}/sub-properties/{domainName}/policy/history.

  5. Review the rule information returned in the Policy response.

The response includes up to 100 of the most recent versions, not including the current version. If there are more than 100 versions of a policy, the oldest is discarded. (For example, version 101 replaces version 1.)

Data

This section shows you the data model for the Akamai Cloud Embed API. The main “{Object}” sections reveal an example of the JSON returned for a GET call. The “{Object} Members” sub-sections illustrate elements that are required or optional, based on the call method. For example, “required” indicates the element must be used in the request body for a PUT method call, and it is always included in the response for a GET call.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

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

SubCustomer

Allows you to add or update a subcustomer.

Download schema: subcustomerID-add-get.json

Sample GET response:

[
    {
        "customerID": "abc-123",
        "geo": "FR",
        "subPropertyIDs": [
            "www.example.com",
            "www.example.biz",
            "www.example.net",
            "www.example.co.uk"
        ]
    }
]

SubCustomer members

Member Type Required Description
geo String The geographic location of the subcustomer.

SubProperty

Lists ID, domain, and geographic information for a subproperty, which is the subcustomer’s domain.

Download schema: subproperty-get-all-for-subcustomer.json

Sample GET response:

[
    {
        "subPropertyID": "www.example.com",
        "customerID": "abc-123"
    },
    {
        "subPropertyID": "www.example.biz",
        "customerID": "abc-123"
    },
    {
        "subPropertyID": "www.example.com.net",
        "customerID": "def-456"
    },
    {
        "subPropertyID": "www.example.com.co.uk",
        "customerID": "def-456"
    }
]

SubProperty members

Member Type Required Description
customerID String The ID of the customer associated with the subproperty.
geo String The geographic location of the subcustomer.
subPropertyID String A unique string representing the subcustomer’s domain.

Policy

Encapsulates rules consisting of match criteria and resulting behavior settings to be applied for a specific subcustomer

Download schema: policy-rule.json

Sample GET response:

{
    "rules": [
        {
            "matches": [
                {
                    "name": "http-method",
                    "value": "GET"
                }
            ],
            "behaviors": [
                {
                    "params": {
                        "originBasePath": "-",
                        "cacheKeyValue": "-",
                        "digitalProperty": "www.example.com",
                        "cacheKeyType": "origin",
                        "httpPort": 80,
                        "hostHeaderValue": "-",
                        "originDomain": "www.example.com",
                        "hostHeaderType": "origin"
                    },
                    "name": "origin",
                    "value": "-"
                },
                {
                    "type": "fixed",
                    "name": "caching",
                    "value": "1m"
                }
            ]
        }
    ]
}

Policy members

Member Type Required Description
rules Policy.rules[] The set of matches and behaviors for this subcustomer policy.
Policy.rules[]: The set of matches and behaviors for this subcustomer policy.
behaviors Policy.rules[].behaviors[] The behaviors to apply to requests that meet the match criteria set in this policy.
matches Policy.rules[].matches[] The criteria that identify which requests to process. When a request matches the criteria, the behaviors are applied to the request.
Policy.rules[].behaviors[]: The behaviors to apply to requests that meet the match criteria set in this policy.
name Enumeration The behavior to apply to incoming requests that meet the match criteria. Available behaviors include: access-control, cachekey-query-args, caching, content-characteristics, content-compression, content-refresh, downstream-caching, geo-blacklist, geo-whitelist, ip-blacklist, ip-whitelist, large-file-optimization, modify-outgoing-request-path, origin, origin-characteristics-behavior, prefetch, real-user-monitoring, referer-blacklist, referer-whitelist, site-failover, sureroute, token-auth. Behaviors are discussed in Matches and Behaviors.
params Object The set of options that determine how the behavior operates.
type String The format to use for the value element.
value String The values to use for the selected behavior.
Policy.rules[].matches[]: The criteria that identify which requests to process. When a request matches the criteria, the behaviors are applied to the request.
name Enumeration The type of match. Available match types include: client-ip, cookie, header, host-name, http-method, url-extension, url-filename, url-path, url-querystring, url-scheme, url-wildcard. Match types are discussed in Matches and Behaviors.
negated Boolean If set to true, the behaviors set in this rule are applied when an incoming request does not meet the match criteria.
value String The value to match.

Matches and Behaviors

A match defines the criteria that must be met in a request for subcustomer content in order to apply the behaviors set in a rule.


Behaviors determine the settings that should be applied to the delivery of subcustomer content. (A behavior’s settings are applied when a request is received for a subcustomer’s content, that meets the rule’s match criteria.)

client-ip

Used as a match criteria when creating or updating a policy. The IP address associated with the requesting client is used to determine the match. You can specify individual IP addresses, or CIDR blocks (that express a range of addresses).

Download schema: client-ip-match.json

client-ip members

Member Type Required Description
name Enumeration Enter client-ip to match based on the requesting client’s IP address.
negated Boolean If set to true, the behaviors set in the subcustomer policy are applied when an incoming request does not meet the match criteria.
params client-ip.params[] Specifies each set of addresses along with criteria to match them.
value String All match criteria require the value member, but client-ip does not use one. Specify a dash for this member (-).
client-ip.params[]: Specifies each set of addresses along with criteria to match them.
ipFromHeader Enumeration When matching the X-Forwarded-For header, specifies which IP address to match in the list, either the first IP address, or all to match any.
ipOrCidrList Array Enter one or more specific IP addresses or CIDR blocks of IP addresses. If a requesting client is associated with one of these IP addresses, the behaviors set in this policy are applied. For example, ["1.2.3.4", "5.6.7.8", "192.168.100.14/24", "2001:db8:abcd:8000::/50"].
source Enumeration Specifies where to find the IP address, either connectingIp for the requesting client’s IP address, headers for the X-Forwarded-For header, or both to match either location.

Used as a match criteria when creating or updating a policy. It lets you include specific cookie names for use when matching on an incoming request.

Download schema: cookie-match.json

cookie members

Member Type Required Description
name Enumeration Enter cookie to use cookie names when matching on the incoming request.
negated Boolean If set to true, the behaviors set in the subcustomer policy are applied when an incoming request does not meet the match criteria.
value String Specifies the case-insensitive cookie name to match on. You can follow the cookie name with a space-delimited list of cookie values to match against, all of which are case-sensitive. Cookie name and cookie values do not support white spaces. Currently, the + ! ( ) [ ] { } characters are not supported, even though they are normally supported for use in cookies. For example, cookiename cookievalue1 cookievalue2.

Used as a match criteria when creating or updating a policy. Associated behaviors are applied if a header or header value you specify in this match criteria are included with a request.

Download schema: header-match.json

header members

Member Type Required Description
name Enumeration Enter header to match on an incoming request header or header value.
negated Boolean If set to true, the behaviors set in the subcustomer policy are applied when an incoming request does not meet the match criteria.
value String Enter a header name, and optionally include an associated header value, for the match (for example, Some-Header-Name or Some-Header-Name "some string value" "another value" or ). Separate multiple header value entries with spaces. Header values are also case sensitive.

host-name

Used as a match criteria when creating or updating a policy. Include this to match on hostnames listed in the incoming request’s Host header.

Download schema: host-name-match.json

host-name members

Member Type Required Description
name Enumeration Enter host-name to match on hostnames listed in the incoming request’s Host header.
negated Boolean If set to true, the behaviors set in the subcustomer policy are applied when an incoming request does not meet the match criteria.
value String Enter a space-separated list of hostnames to match. You can use the ? and * wildcards with this match value.

http-method

Used as a match criteria when creating or updating a policy. Include this to match on a set of HTTP methods.

Download schema: http-method-match.json

http-method members

Member Type Required Description
name Enumeration Enter http-method to match based on HTTP method.
negated Boolean If set to true, the behaviors set in the subcustomer policy are applied when an incoming request does not meet the match criteria.
value String Enter the HTTP methods to match on, separated by spaces. The following values are supported: GET, HEAD, POST, PUT, DELETE, OPTIONS, TRACE, and CONNECT.

url-extension

Used as a match criteria when creating or updating a policy. It lets match on the extension in the incoming request. This match criteria has no effect on URL paths that do not include a file extension.

Download schema: url-extension-match.json

url-extension members

Member Type Required Description
name Enumeration Enter url-extension to match on the extension in the incoming request.
negated Boolean If set to true, the behaviors set in the subcustomer policy are applied when an incoming request does not meet the match criteria.
value String Enter the filename extensions to match on, separated by spaces. This string cannot be empty and entries are case sensitive.

url-filename

Used as a match criteria when creating or updating a policy. It lets you match on the filename and extension included in the incoming request.

Download schema: url-filename-match.json

url-filename members

Member Type Required Description
name Enumeration Enter url-filename to match on the filename and extension included in the incoming request.
negated Boolean If set to true, the behaviors set in the subcustomer policy are applied when an incoming request does not meet the match criteria.
value String Enter a space-separated list of filenames to match. The filename can be in any subdirectory or URL path. For example, filename.ext matches on both /filename.ext and /path/to/filename.ext.

url-path

Used as a match criteria when creating or updating a policy. It lets you match on the first path component in the incoming request. The first path component is the section directly after the base URL.

Download schema: url-path-match.json

url-path members

Member Type Required Description
name Enumeration Enter url-path to match on the first path component in the incoming request.
negated Boolean If set to true, the behaviors set in the subcustomer policy are applied when an incoming request does not meet the match criteria.
value String Enter a space-separated list of path names to match on. Do not include slashes with your entry. This match is case sensitive and does not support wildcard characters. For example, entering static static2 matches on all URI paths that begin with /static/ or /static2/, like /static/dir1/dir2/filename.ext.

url-querystring

Used as a match criteria when creating or updating a policy. It lets you match on a combination of query string parameters and their values.

Download schema: url-querystring-match.json

url-querystring members

Member Type Required Description
name Enumeration Enter url-querystring to match on a combination of query string parameters and their values.
params url-querystring.params[] The parameters that define how you want to handle query strings for your implementation.
url-querystring.params[]: The parameters that define how you want to handle query strings for your implementation.
key String Enter the query string to match on. You can use the ? and * wildcards with your entry.
value String Enter the query string values to match on, separated by spaces. You can use the ? and * wildcards with this match value.

url-scheme

Used as a match criteria when creating or updating a policy. It lets you match on the protocol or scheme (HTTP or HTTPS) of an incoming request.

Download schema: url-scheme-match.json

url-scheme members

Member Type Required Description
name Enumeration Enter url-scheme to match on the protocol or scheme (HTTP or HTTPS) of an incoming request.
negated Boolean If set to true, the behaviors set in the subcustomer policy are applied when an incoming request does not meet the match criteria.
value Enumeration Enter either HTTP or HTTPS depending on the protocol you want to match on.

url-wildcard

Used as a match criteria when creating or updating a policy. It lets you use wildcards when matching on the incoming request path, minus any query strings. This match type only supports the * wildcard.

Download schema: url-wildcard-match.json

url-wildcard members

Member Type Required Description
name Enumeration Enter url-wildcard to use wildcards when matching on the incoming request path, minus query strings.
negated Boolean If set to true, the behaviors set in the subcustomer policy are applied when an incoming request does not meet the match criteria.
value String Enter the path to match on. If you do not include a wildcard, the incoming request must match the value exactly as entered.

access-control

Used as a behavior when creating or updating a policy. It lets you deny client requests based on the selected match conditions.

Download schema: access-control-behavior.json

access-control members

Member Type Required Description
name Enumeration Enter access-control to deny client requests based on any of the available match conditions.
type Enumeration Either deny or allow an incoming request that matches on this rule.
value String Enter strings of up to 64 characters to annotate logs with the approval or denial reason. Alphanumeric characters, dashes, and underscores are valid. For allow, you can also use the * wildcard character. Separate strings with spaces.

cachekey-query-args

Used as a behavior when creating or updating a policy. It specifies how to handle query-string arguments in incoming requests.

Download schema: cachekey-query-args-behavior.json

cachekey-query-args members

Member Type Required Description
name Enumeration Enter cachekey-query-args to define how query-string arguments are handled when creating the cache key for the Akamai edge server.
type Enumeration Options for handling query-string arguments. Use include-all to include all query-string values in the cache key. Use include to only append the query arguments listed in the cache key’s value attribute. Use ignore-all to remove all query-string arguments from the incoming request. Use ignore to not include the query arguments listed in the value attribute in the cache key.
value String If using include or ignore as the caching type, list the query strings to match on. The match is case sensitive. Use spaces to separate entries. Add an equal sign to the value to match the query string argument exactly and also extend the value of the query argument. For example, entering product=1 matches both product=1 and product=123 but not product=234. Not required for the include-all and ignore-all type settings.

caching

Used as a behavior when creating or updating a policy. Include it to provide time-to-live (TTL) cache settings for subcustomers.

Download schema: caching-behavior.json

caching members

Member Type Required Description
name Enumeration Enter caching to configure the time-to-live (TTL) settings for a subcustomer based on specific match conditions.
type Enumeration Select the type of cache response to use. Choose no-store to never cache the response and evict any existing cache entry; bypass-cache to never cache the response and retain the existing cache entry; fixed to cache the response for the time period defined in value; honor to cache based on the values in the cache-control and expires headers; honor-cc to cache based on the values in the cache-control header; or honor-expires to cache based on the values in the expires header.
For the honor-based options, objects currently in cache may be used with the current request. Also, if the response doesn’t include the Cache-Control or Expires header, the object is cached based on the time listed in the value parameter. For the honor and honor-cc options, if the Cache-Control header includes a no-store or no-cache directive, the Akamai server doesn’t cache the response.
No caching occurs if the Expires header has an RFC 2616 time string in the past or includes -1, which helps prevent downstream caching.
value String Ignored for the no-store and bypass-cache types. For all other type settings, enter a simple duration string, which is an integer followed by a specifier to represent seconds (s), minutes (m), hours (h), or days (d). For example: 86400s, or 1440m, or 24h, or 1d all represent a TTL setting of one day.

content-char-dynamic-web

Used as a behavior when creating or updating a policy. If you’re using Integrated Cloud Acceleration, this uses SureRoute to optimize the forward path to the origin server. It controls embedded object pre-fetching, situational image compression, and Real User Monitoring (RUM) capabilities.

Download schema: content-char-dynamic-web-behavior.json

content-char-dynamic-web members

Member Type Required Description
name Enumeration Enter content-characteristics, the behavior that includes this optimization.
params content-char-dynamic-web.params Optimization settings for this behavior.
type Enumeration Enter dynamic-web-content to use Akamai’s SureRoute feature to optimize the forward path to the origin server.
value String Ignored for this behavior. For consistency, enter a dash (-).
content-char-dynamic-web.params: Optimization settings for this behavior.
mobileImageCompressionEnabled Boolean Enable or disable JPEG compression based on mobile network conditions.
prefetchEnabled Boolean Inspects HTML responses and prefetches embedded objects in HTML files. Prefetching works on any page that includes <img>, <script>, or <link> tags that specify relative paths. It also works when the resource hostname matches the request domain in the HTML file, and it is part of a fully qualified URI. When set to true, edge servers prefetch objects with the following file extensions: aif, aiff, au, avi, bin, bmp, cab, carb, cct, cdf, class, css, doc, dcr, dtd, exe, flv, gcf, gff, gif, grv, hdml, hqx, ico, ini, jpeg, jpg, js, mov, mp3, nc, pct, pdf, png, ppc, pws, swa, swf, txt, vbs, w32, wav, wbmp, wml, wmlc, wmls, wmlsc, xsd, and zip.
realUserMonitoring Boolean Set to true to enable Real User Monitoring (RUM). For objects with a text/html content type, RUM inserts a JavaScript tag that uses the Navigation Timing browser API to gather specific performance metrics. The sampling rate for RUM is 5% of requests that trigger this behavior.
sureRouteTestObjectPath String Enable SureRoute by entering a valid path to the test object on your origin. A valid test object is between 4 KB to 12 KB compressed and requires no authorization. SureRoute looks for the optimal route between an edge server and an origin server.

content-char-large-file

Used as a behavior when creating or updating a policy. Include it to optimize the delivery of large file downloads of up to 1.8 GB. This behavior uses partial object caching with pre-fetched object data.
As a best practice, only use this behavior if you serve large files. Otherwise, the Akamai platform may send additional requests to your origin. When using Large File Optimization, if an object doesn’t meet the minimum size criterion of 10 MB, the platform requests the entire object from the origin.

Download schema: content-char-large-file-behavior.json

content-char-large-file members

Member Type Required Description
name Enumeration Enter content-characteristics, the behavior that includes this optimization.
params content-char-large-file.params The parameters that define how you want to handle file optimization for your implementation.
type Enumeration Enter large-files to optimize the delivery of large file downloads of up to 1.8 GB.
value String Ignored for this behavior. For consistency, enter a dash (-).
content-char-large-file.params: The parameters that define how you want to handle file optimization for your implementation.
objectSize Enumeration Options include: lt1mb for objects less than 1 MB, 1mbto10mb for objects 1 MB to 10 MB, 10mbto100mb for objects 10 MB to 100 MB, and gt100mb for objects 100 MB and larger. Both 10mbto100mb and gt100mb enable Large File Optimization. Using lt1mb or 1mbto10mb disables partial object caching and prevents the platform from serving large objects.

content-char-streaming

Used as a behavior when creating or updating a policy. Include it to optimize cache and network timeout conditions for on-demand video content. The Akamai platform examines the URI file extension and path for the media format then automatically optimizes: cache efficiency, time-to-live, automated failover, downstream Content-Type headers, and network timeout settings.

Download schema: content-char-streaming-behavior.json

content-char-streaming members

Member Type Required Description
name Enumeration Enter content-characteristics, the behavior that includes this optimization.
params content-char-streaming.params The parameters that define how you want to handle the streaming of on-demand video content.
type Enumeration Enter streaming-video-on-demand to optimize cache and network timeout conditions for on-demand video content.
value String Ignored for this behavior. For consistency, enter a dash (-).
content-char-streaming.params: The parameters that define how you want to handle the streaming of on-demand video content.
segmentDurationDASH Number Duration in seconds for Dynamic Adaptive Streaming over HTTP (DASH) media segments. Supported range is 0.0 to 15.0, with only one decimal place allowed. If you omit this member, the default segment duration for DASH is used (2.5 seconds).
segmentDurationHDS Number Duration in seconds for HTTP Dynamic Streaming (HDS) media segments. Supported range is 0.0 to 15.0, with only one decimal place allowed. If you omit this member, the default segment duration for HDS is used (six seconds).
segmentDurationHLS Number Duration in seconds for HTTP Live Streaming (HLS) media segments. Supported range is 0.0 to 15.0, with only one decimal place allowed. For recommended best practices, see Apple Technical Note 2224. If you omit this member, the default segment duration for HLS is used (10 seconds).
segmentDurationSmooth Number Duration in seconds for Microsoft Smooth Streaming media segments. Supported range is 0.0 to 15.0, with only one decimal place allowed. If you omit this member, the default segment duration for HDS is used (two seconds).

content-compression

Used as a behavior when creating or updating a policy to provide compression settings. You can enable gzip compression, decompress objects before delivering them to the client, or maintain the origin’s compression settings.

Download schema: content-compression-behavior.json

content-compression members

Member Type Required Description
name Enumeration Enter content-compression to enable this behavior.
type Enumeration Select the appropriate compression setting for this behavior. Use always to compress all objects served to clients that send an Accept-Encoding:*gzip* header, never to decompress objects served to the client, and follow-origin to retain the origin’s compression settings.
value String Enter the MIME types to compress, separated by spaces. The maximum string length is 1024 characters, and wildcards can be used (*). Enter - if you do not want to apply compression to any MIME type.

content-refresh

Used as a behavior when creating or updating a policy. Lets you invalidate CDN cache at an explicit date and time. This behavior uses epoch time to denote when a request should receive a new copy of the object or a revalidated one.

Download schema: content-refresh-behavior.json

content-refresh members

Member Type Required Description
name Enumeration Enter content-refresh to invalidate CDN cache at an explicit date/time.
params content-refresh.params Content revalidation settings for this behavior.
type Enumeration Declares the format of the value element. Enter epoch to use epoch time; date-time to use an ISO 8601 time value (YYYY-MM-DDThh:mm:ssZ); date to use an ISO 8601 date value (YYYY-MM-DD), which invalidates cache at midnight GMT on the specified date; and natural to invalidate content immediately upon publication of the content policy.
value String The time after which the invalidation of objects in cache should occur.
content-refresh.params: Content revalidation settings for this behavior.
mustRevalidate Boolean If true, the edge server only serves content from cache if it has been revalidated after the given invalidation time. If false, the edge server may serve content from cache if an attempt to revalidate the content fails to receive a response from the origin server.

downstream-caching

Used as a behavior when creating or updating a policy. Include this to control downstream caching of alternate content. Only use this behavior if site failover is enabled for the alternate hostname property. If you do not include this behavior, your subcustomer policy uses the downstream caching settings specified in the alternate hostname property. To enable site failover, use the Subcustomer Enablement behavior in Property Manager.

Download schema: downstream-caching-behavior.json

downstream-caching members

Member Type Required Description
name Enumeration Enter downstream-caching to control downstream caching of alternate content.
value Enumeration Enter no-store to serve the alternate response with an HTTP Cache-Control: no-store header. Enter no-cache to serve the alternate response with an HTTP Cache-Control: no-cache header.

geo-blacklist

Used as a behavior when creating or updating a policy. Include this to block access to content based on the continent, country, region/state, or designated marketing area (DMA) of the requesting IP address. All other geographic areas are allowed.

Download schema: geo-blacklist-behavior.json

geo-blacklist members

Member Type Required Description
name Enumeration Enter geo-blacklist to block access to content based on the geographic location of the requesting IP address.
type Enumeration Declares the type of geographies to blacklist. Valid types are continent, country, region, and dma.
value String Enter a space-separated list of geographies. If matching on region, enter the values using a country:region format like US:AK, which corresponds to the state of Alaska in the United States. If matching on dma, enter the integer that represents the Designated Market Area (DMA) to blacklist. See the EdgeScape Data Codes for a list of valid values.

geo-whitelist

Used as a behavior when creating or updating a policy. Include this to allow access to content based on the continent, country, region/state, or designated marketing area (DMA) of the requesting IP address. All other geographic areas are denied.

Download schema: geo-whitelist-behavior.json

geo-whitelist members

Member Type Required Description
name Enumeration Enter geo-whitelist to allow access to content based on the geographic location of the requesting IP address.
type Enumeration Declares the type of geographies to whitelist. Valid types include: continent, country, region, and dma.
value String Enter a space-separated list of geographies. If matching on region, enter the values using a country:region format like US:AK, which corresponds to the state of Alaska in the United States. If matching on dma, enter the integer that represents the Designated Market Area (DMA) to blacklist. See the EdgeScape Data Codes for a list of valid values.

ip-blacklist

Used as a behavior when creating or updating a policy. Include this to block access based on the requesting IP address.

Download schema: ip-blacklist-behavior.json

ip-blacklist members

Member Type Required Description
name Enumeration Enter ip-blacklist to block access based on the requesting IP address.
value String Enter a space-separated list of IP addresses or CIDR blocks to deny. All other IP addresses are allowed.

ip-whitelist

Used as a behavior when creating or updating a policy. Include this to allow access based on the requesting IP address. Only the IP addresses listed are allowed access.

Download schema: ip-whitelist-behavior.json

ip-whitelist members

Member Type Required Description
name Enumeration Enter ip-whitelist to allow access based on the requesting IP address.
value String Enter a space-separated list of IP addresses or CIDR blocks to allow. All other IP addresses are blocked.

modify-outgoing-request-path

Used as a behavior when creating or updating a policy. Include this to provide options for altering the request URL before it is sent to origin.

Download schema: modify-outgoing-request-path-behavior.json

modify-outgoing-request-path members

Member Type Required Description
name Enumeration Enter modify-outgoing-request-path to alter the request URL before it is sent to origin.
type Enumeration Set the type of request path change to use. Enter remove to remove the first occurrence of the value from the outgoing request URL; replace-all to replace the original request path before the filename with the path specified in value; or replace to search for a portion of the original request URL and replace it with a value you define.
value String If using remove, enter the string of characters to remove from the forward request. Leading and trailing slashes are not removed. If using replace-all, enter the URL path to replace the original incoming URL path. If using replace enter a value in this format: /find/path/###/replace/ path/, where ### separates the string to find and the string to replace. For example, if your base URL is www.example.com/dir1/dir2/dir3/index.html and you enter /dir1/dir2/###/dir4/ as the value, the resulting URL is www.example.com/dir4/dir3/index.html.

origin

Used as a required behavior when creating or updating a policy. It provides origin settings for the specific subcustomer. You need to include: origin DNS hostname, forward host header, and cache key. Optional settings include the origin base path and ports.

Download schema: origin-behavior.json

origin members

Member Type Required Description
name Enumeration Enter origin to set up the origin behavior, which is required for every content policy.
params origin.params Origin settings for the policy.
value String Enter a dash (-) for this parameter.
origin.params: Origin settings for the policy.
cacheKeyType Enumeration Enter the method to use when constructing the cache key. Use digital_property if the response is different for each property, origin if the origin response is the same regardless of property, or fixed to set a specific cache key value.
cacheKeyValue String If cacheKeyType is fixed, enter a valid domain name for the hostname portion of the cache key. Use a dash (-) to indicate no value.
digitalProperty String Enter the hostname used by the client to access the site or application. Use a valid domain name like www.example.com or blogs.example.com.
hostHeaderType Enumeration For requests sent to this origin, enter the host header value to generate. Use digital_property to have the host header match the digital property, origin to use the originDomain value as the host header, and fixed to use the hostHeaderValue as the host header.
hostHeaderValue String If hostHeaderType is fixed enter a valid domain name to use in the host header. Use a dash (-) to indicate no value.
originDomain String Enter the origin hostname you provide to subcustomers when you provision services. Your entry can either be a valid domain name or an IP address.

origin-characteristics

Used as a behavior when creating or updating a policy. Include this if you have Integrated Cloud Acceleration (ICA), to select the type of origin supporting your Akamai Cloud Embed implementation. Use the origin behavior to configure origin settings for your subcustomers at the policy level.

Download schema: origin-characteristics-behavior.json

origin-characteristics members

Member Type Required Description
name Enumeration Use the origin-characteristics behavior to select the type of origin you are using for your Akamai Cloud Embed implementation.
type Enumeration The type of origin supporting your implementation. Enter azure if you use an Azure Media Services live origin. Use unknown for all other origins.

referer-blacklist

Used as a behavior when creating or updating a policy. Include this to block access based on the Referer request header. This behavior helps verify that the client is a browser that supports RFC 2616, section 14.36, and that the referring HTML page is served from a domain trusted by the content owner.

Download schema: referer-blacklist-behavior.json

referer-blacklist members

Member Type Required Description
name Enumeration Enter referer-blacklist to block access based on the Referer request header.
value String Enter a space-separated list of Referer header values to disallow. Use the * wildcard to match on a substring within the header value.

referer-whitelist

Used as a behavior when creating or updating a policy. Include this to allow access based on the Referer request header. This behavior helps verify that the client is a browser that supports RFC 2616, section 14.36, and that the referring HTML page is served from a domain trusted by the content owner.

Download schema: referer-whitelist-behavior.json

referer-whitelist members

Member Type Required Description
name Enumeration Enter referer-whitelist to allow access based on the Referer request header.
value String Enter a space-separated list of Referer header values to allow. Use the * wildcard to match on a substring within the header value.

site-failover

Used as a behavior when creating or updating a policy. Include this to define the alternate hostname and path to use when the edge server can’t contact the origin server.

Download schema: site-failover-behavior.json

site-failover members

Member Type Required Description
name Enumeration Enter site-failover to define an alternate response to serve when the edge server can’t contact the origin server.
params site-failover.params These are failover settings.
type Enumeration Select the failover action to use. Enter serve-301 for 301 redirects, serve-302 for 302 redirects, or serve-alternate to send a request to an alternate hostname and path.
site-failover.params: These are failover settings.
alternateHostname String Enter the domain of the hostname to failover to. Enter a dash (-) to use the original hostname when constructing the new URL.
alternatePath String Enter a valid URI path to failover to. Always include the initial slash. Include the closing slash to change the URL path but keep the original filename. Enter a dash (-) to use the original path when constructing the new URL.
httpResponseStatus String Enter a space-separated list of the HTTP status codes served to the client when site-failover is not in effect. You can use integer ranges (for example, 404, 500:504).
preserveQueryString Boolean Enter true to retain the query string from the original request URL, or enter false to remove the query string.

token-auth

Used as a behavior when creating or updating a policy. This lets you use tokens to control access to content. You can choose to transmit the token in a cookie, header, or query parameter.

Download schema: token-auth-behavior.json

token-auth members

Member Type Required Description
name Enumeration Enter token-auth to use tokens to control access to content.
params token-auth.params These are token parameters.
value String This is ignored for this match type, but required for consistency in the API. Set the value to a dash (-).
token-auth.params: These are token parameters.
aclDelimiter String Enter a single character to separate the access control list (ACL) fields. You cannot use alphanumeric characters, or any of the following character class: [.&`=/:%]. If nothing is specified, ! is used as the delimiter.
escapeTokenInputs Boolean Enter true to escape the input values before adding them to the token. Enter false to not escape the input values.
hmacAlgorithm Enumeration Enter the algorithm to use for the token’s hash-based message authentication code (HMAC) field. Valid entries are SHA256, SHA1, or MD5.
ignoreQueryString Boolean Enter true to remove the URL’s query strings when computing the token’s HMAC algorithm. Enter false to include the query strings in the algorithm.
key String Enter an even number of Hex digits for the token key. An entry can be up to 64 characters in length.
salt String Enter a salt for the token that does not exceed 250 characters, and does not include this character class: [~@#%^&=/|\].
tokenDelimiter String Enter a single character to separate the individual token fields. You cannot use character in the following class: [a-zA-Z0-9=&/\:%]. If nothing is specified, ~ is used as the delimiter.
tokenName String Enter a string for the token name. The string must match on the following regular expression: ^([a-zA-Z_][a-zA-Z0-9-_]*)$.
transitionKey String Enter an even number of hex digits for the token transition key. An entry can be up to 64 characters in length.

Errors

This section shows you how to handle various kinds of errors this API generates, and lists the range of HTTP status codes along with their likely causes.

Error responses

The following example shows an error response for a request processed by this API:

{
    "errorCode" : 403,
    "message" : "Authorization failed",
    "description" : "The user is not authorized to access the policies or subcustomers associated with the given property id",
    "helpLink" : "https://developer.akamai.com/api/delivery-policies/errors.html#403",
    "errorInstanceId" : "31f1a7532f",
}

You would expect to see a message like this if the property ID is not valid or is not configured correctly.

HTTP status codes

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

Code Description
200 The operation was successful.
201 Resource successfully created.
202 Resource successfully accepted.
400 Bad Request.
401 Authentication failure.
403 Access is forbidden.
404 Resource not found.
408 Request timeout.
500 Internal server error.
503 Too many requests. Service is temporarily unavailable.

Last modified: 11/12/2018