This guide helps you onboard an edge hostname using the Property Manager API. The instructions below describe the process and high-level requirements for each step. Links to the full reference information on each operation or object type can be found throughout this guide.

Note: Ensure you have access to the API via a configured client and that you set the correct access level for the service. See Getting Started in the PAPI documentation for more information.

Make sure you set the correct access level when provisioning the API token.

CPS Prerequisite for TLS

You must have a certificate enrollmentId to configure Enhanced TLS or to utilize HTTPS traffic on Standard TLS. You can skip this section if you are using Shared Certificates or will only utilize HTTP traffic on Standard TLS hostnames.

The following instructions show you how to create or retrieve a certificate using the Certificate Provisioning System API:

Create a new enrollment ID

If the certificate you want doesn’t already exist, you need to run the CPS API’s Create an enrollment operation. It takes several hours to fully deploy a new certificate.

Example request:

POST /cps/v2/enrollments{?contractId,deploy-not-after,deploy-not-before}

Example response:

{
    "enrollment": "/cps/v2/enrollments/10002",
    "changes": [
    "/cps/v2/enrollments/10002/changes/10002"
    ]
}

Get an existing enrollment ID

Get an existing enrollment ID

Example Request:

GET /cps/v2/enrollments?contractId=ctr_12345

Example response:

{
    "enrollments": [
        {
            "location": "/cps-api/enrollments/**10002**",
            ...
            "csr": {
                "cn": "www.example.com",
                "sans": [
                    "www.foo.com",
                ]
            ...
        },
        "pendingChanges": [
            "/cps/v2/enrollments/10000/changes/10000"
        ]
}

Strip the leading path expression from the object’s location member, and use that string value as the certEnrollmentId. For example, if the location is "/cps-api/enrollments/10002", the certEnrollmentId is "10002".

Note: Responses that contain the pendingChanges member are not fully deployed. Ensure the certificate is fully deployed before switching over the CNAME.

Get required parameters

The contractId, groupId, and propertyId are required to perform various operations in this guide. This section provides direction to where to get these values so you can store them for later use.

1. Run the List contracts operation and store the relevant contractId.

2. Run the List groups operation and store the relevant groupId.

3. Run the List properties operation or use the Search properties endpoint and store the relevant propertyId.

Create an edge hostname

You can use three approaches to secure edge hostnames: Standard TLS, Enhanced TLS, or a Shared Certificate. Once the hostname is active, you can Update a property’s hostnames to assign it to a property. After you activate a property, modifying your DNS to map the origin hostname to the edge hostname ultimately enables traffic on the property.

1. Create a new EdgeHostname object.

2. GET a list of products from /papi/v1/products{?contractId} and select the appropriate productId from the response’s product.items array.

3. Set the domainPrefix to the original hostname, for example www.example.com.

4. Set domainSuffix to:

   • edgesuite.net for Standard TLS

   • edgekey.net for Enhanced TLS

   • akamized.net for Shared Certificates

5. Set ipVersionBehavior to IPV4, IPV6, or IPV6_COMPLIANCE to support both.

6. Verify that your EdgeHostname object resembles the example for your certificate type below:

   • Standard TLS: { "productId": "prd_Dynamic_Site_Del", "domainPrefix": "www.foo.com", "domainSuffix": "edgesuite.net", "secureNetwork": "STANDARD_TLS", "ipVersionBehavior": "IPV4" }

   • Enhanced TLS: { "productId": "prd_Rich_Media_Accel", "domainPrefix": "www.foo.com", "domainSuffix": "edgekey.net", "secureNetwork": "ENHANCED_TLS", "ipVersionBehavior": "IPV4", "certEnrollmentId": "10277" }

   • Shared Certificate: { "productId": "Adaptive_Media_Delivery", "domainPrefix": "www-foo_com", "domainSuffix": "akamaized.net", "secureNetwork": "SHARED_CERT", "ipVersionBehavior": "IPV4" }

7. POST the object to /papi/v1/edgehostnames{?contractId,groupId}. See Create a secure edge hostname for more information.

8. Optionally GET the response object’s edgeHostnameLink or the Location header to poll the new edge hostname’s deployment status. This runs the Get an edge hostname operation.

Update the property’s hostname

After creating a new edge hostname, you need to assign the edge hostname to a property.

1. Run List a property’s hostnames and store the response’s hostnames.items array.

2. Modify the Hostname object by adding objects that represent new edge hostnames.

   1. Set the cnameType to EDGE_HOSTNAME.

   2. edgeHostnameId. Set to a unique identifier for the edge hostname, prefixed with ehn_ by default.

   3. Set cnameFrom to the original origin vs hostname.

   4. Optionally set the cnameTo to the hostname for edge content, corresponding to the edge hostname object’s edgeHostnameDomain member.

3. Verify that your Hostname object resembles the example for your certificate type below:

   • Standard TLS: [ { "cnameType": "EDGE_HOSTNAME", "cnameFrom": "www.example.com", "cnameTo": "www.example.com.edgesuite.net", "edgeHostnameId": "ehn_12345" } ]

   • Enhanced TLS: [ { "cnameType": "EDGE_HOSTNAME", "cnameFrom": "www.example.com", "cnameTo": "www.example.com.edgekey.net", "edgeHostnameId": "ehn_12345" } ]

   • Shared Certificate: [ { "cnameType": "EDGE_HOSTNAME", "cnameFrom": "mywebsite.akamaized.net", "cnameTo": "mywebsite.akamaized.net", "edgeHostnameId": "ehn_12345" } ]

4. PUT the array to /papi/v1/properties/{propertyId}/versions/{propertyVersion}/hostnames{?contractId,groupId,validateHostnames}, passing in the etag as an If-Match header. See the Update the property’s hostname operation for more details.

   NOTE: You can optionally set the validateHostnames query parameter to false if you don’t want to perform potentially slower validation tests on the set of hostnames.

Activate your property

After creating a new edge hostname and assigning it to a property, you need to deploy the modified property version to the network.

1. Create an Activation POST object.

2. Set propertyVersion to the property version targeted by this activation.

3. Set network to either STAGING or PRODUCTION.

4. Set activationType to ACTIVATE.

5. Set notifyEmails to a list of email strings to notify when the activation status changes.

6. Verify that your Activation object resembles the example below:

   {
       "propertyVersion": 1,
       "network": "STAGING",
       "activationType": "ACTIVATE",
       "note": "Sample activation",
       "notifyEmails": [
           "you@example.com",
           "them@example.com"
       ]
   }
   

7. POST the object to /papi/v1/properties/{propertyId}/activations{?contractId,groupId}. See Activate your property for more information.

Enable traffic

After creating a new edge hostname, assigning it to a property, and activating the property, you still need to modify your DNS configuration to direct the origin’s traffic to the new edge hostname, otherwise known as Akamaizing your content.

Edge hostnames are formed from the combined domainPrefix and domainSuffix included in the POST request. In this case custom.example.com.edgesuite.net indicates standard HTTP traffic:

{
    "productId": "prd_PPP",
    "domainPrefix": "custom.example.com",
    "domainSuffix": "edgesuite.net",
    "secure": true,
    "ipVersionBehavior": "IPV4",
    "slotNumber": 12345
}

HTTPS typically uses an edgekey.net suffix. The POST request tells Akamai’s network of DNS servers to map it to local server names, but for the hostname to ultimately activate, you need to update your own DNS record to map your origin hostname to the edge hostname. A resulting DNS resolution looks like this:

$ host -v custom.example.com
Trying "custom.example.com"
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 14682
;; flags: qr aa rd ra; QUERY: 1, ANSWER: 3, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;custom.example.com. IN      A

;; ANSWER SECTION:
custom.example.com.     300     IN      CNAME   custom.example.com.edgekey.net.
custom.example.com.edgekey.net. 3701 IN CNAME   e79.x.akamaiedge.net.
e79.x.akamaiedge.net.   11      IN      A       72.246.8.105

The first CNAME entry maps your custom.example.com domain to the custom.example.com.edgekey.net edge hostname, allowing traffic to flow to Akamai’s edge servers. POSTing the new edge hostname implements the second CNAME, which in this case maps the edge hostname to the local e79.x.akamaiedge.net hostname, and in turn to a local IP address.