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 Get 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 need a certificate enrollmentId to configure HTTPS delivery. You can skip this section if you are using default or shared certificates or are using HTTP traffic only.

NOTE: Default certificates are available to Secure by Default customers only. Secure by Default is available on a limited basis. To learn more, contact your account representative.

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

Create a new enrollment ID

If you want to use a custom certificate that 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](https://developer.akamai.com/api/core_features property_manager/v1.html#getgroups) 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 these 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 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

   • akamaized.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" }

   NOTE: If you are creating a default Enhanced TLS certificate, for the enrollment ID, please choose an existing SNI-only Enhanced TLS certificate.

   • 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. To use a default certificate for this hostname, set certProvisioningType to DEFAULT.

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

> NOTE: Include certProvisioningType in your hostname object only when you are using a default certificate, available to customers with the Secure by Default limited release.

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

* Enhanced TLS:

    ```
    [
        {
            "cnameType": "EDGE_HOSTNAME",
            "cnameFrom": "www.example.com",
            "cnameTo": "www.example.com.edgekey.net",
            "edgeHostnameId": "ehn_12345",
            "certProvisioningType": "DEFAULT"
        }
    ]
    ```

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

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

2. If you are using a default certificate for this hostname, you need to perform domain validation to prove to the certificate authority that you control the domain and are authorized to create certificates for it. Use GET includeCertStatus=true{&contractId,groupId,validateHostnames} to get the status of the certificate, which includes the domain validation CNAME target:

   "certStatus": {
     "staging": [
         {
           "status": "NEEDS_VALIDATION",
           "validationCnameTarget": "{token}.www.example.com.akamai-domain.com"
         }
     ],
     "production": [
         {
           "status": "NEEDS_VALIDATION",
           "validationCnameTarget": "{token}.www.example.com.akamai-domain.com"
         }
     ]
   }
   

In your DNS configuration, create a CNAME record for _acme-challeng.<YOUR_DOMAIN> with the value set to the validationCnameTarget.

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. We recommend testing any property configuration changes on the staging network before activating them on the production network, especially when your hostname is already directing end user traffic to the Akamai network. To learn more, see Activating on Staging.

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 this example:

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

In DNS, make sure that your hostname is configured to direct end user traffic to the Akamai network (also known as Akamaizing your content).

1. Verify that all of the necessary components are live on the production network:

   • Property: Call GET /papi/v1/properties/{propertyId}/activations/{activationId}{?contractId,groupId} to ensure that the activation shows network: PRODUCTION and status: ACTIVE.
   • TLS certificates: Call GET /papi/v1/properties/{propertyId}/versions/{propertyVersion}/hostnames? includeCertStatus=true{&contractId,groupId,validateHostnames} to ensure that the certStatus for each hostname shows status: DEPLOYED.

2. Test how the production Akamai network will deliver your site. Use the same method that you used to test on staging, substituting the production edge hostname for the staging edge hostname, for example, example.com.edgesuite.net instead of example.com.edgesuite-staging.net.

3. Modify your DNS configuration to direct the hostname’s traffic to the Akamai network, using a CNAME that points to the Edge hostname.

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 the DNS record for your property hostname to be a CNAME pointing 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.