- Learn Akamai >
- Learn Akamai for Developers >
- Core Features >
- Create edge hostnames using PAPI

Create edge hostnames using PAPI
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
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.
Run the List contracts operation and store the relevant
contractId
.Run the List groups operation and store the relevant
groupId
.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.
Create a new EdgeHostname object.
GET a list of products from
/papi/v1/products{?contractId}
and select the appropriateproductId
from the response’sproduct.items
array.Set the
domainPrefix
to the original hostname, for examplewww.example.com
.Set
domainSuffix
to:edgesuite.net
for Standard TLSedgekey.net
for Enhanced TLSakamaized.net
for Shared Certificates
Set
ipVersionBehavior
toIPV4
,IPV6
, orIPV6_COMPLIANCE
to support both.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" }
POST the object to
/papi/v1/edgehostnames{?contractId,groupId}
. See Create a secure edge hostname for more information.Optionally GET the response object’s
edgeHostnameLink
or theLocation
header to poll the new edge hostname’s deploymentstatus
. 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.
Run List a property’s hostnames and store the response’s
hostnames.items
array.Modify the Hostname object by adding objects that represent new edge hostnames.
Set the
cnameType
toEDGE_HOSTNAME
.edgeHostnameId
. Set to a unique identifier for the edge hostname, prefixed withehn_
by default.Set
cnameFrom
to the original origin vs hostname.Optionally set the
cnameTo
to the hostname for edge content, corresponding to the edge hostname object’sedgeHostnameDomain
member.
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" } ]
PUT the array to
/papi/v1/properties/{propertyId}/versions/{propertyVersion}/hostnames{?contractId,groupId,validateHostnames}
, passing in theetag
as anIf-Match
header. See the Update the property’s hostname operation for more details.NOTE: You can optionally set the
validateHostnames
query parameter tofalse
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.
Create an Activation POST object.
Set
propertyVersion
to the property version targeted by this activation.Set
network
to eitherSTAGING
orPRODUCTION
.Set
activationType
toACTIVATE
.Set
notifyEmails
to a list of email strings to notify when the activation status changes.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" ] }
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.