API

Onboard a property with a Default DV certificate

This workflow uses the Property Manager API (PAPI) to create a property that's protected by a Default Domain Validation (DV) certificate. ​Akamai​ automatically generates a new Default DV certificate and IPv6 edge hostname to securely deliver your content.

📘

Default DV is limited availability

This is an additional service that needs to be added to your contract. However, it hasn't been released to general availability yet. Only a select number of customers can use it. Contact your account team to see if you're eligible. Otherwise, you need to onboard a custom cert property.

Before you begin

Make sure you get these things done before you jump into the workflow.

  • Determine the level of security. What level of security do you need to deliver your content to requesting clients? Have a look at Understand the levels of security to figure out if you need Enhanced or Standard TLS security.

  • Set up authentication for PAPI. To make calls through PAPI, you need to authenticate to ​Akamai​ using tokens you generate in your API client tool.

  • Make sure you have write access to your primary DNS servers. You'll need to modify DNS records during the process.

  • Review limits imposed on PAPI operations. Make sure you don't exceed the rate and resource limits and familiarize yourself with the concurrency control rules this API applies.

1 - Add the origin layer to your DNS

Get the IP address of your existing origin and create an A record in your DNS.

2 - Get contracts, groups, and products

These identifiers specify what modules and features you'll be able to use in your property.

List contracts
Open Recipe
List groups
Open Recipe
List products
Open Recipe

3 - Create a CP code

CP codes track any web traffic handled by edge servers. Each property’s default rule needs a valid CP code to bill and report for the service.

Create a new CP code
Open Recipe

4 - Create a property

Think of a property as a container for your product configuration. Set one up to control how your content is delivered.

Create a new property
Open Recipe

5 - Set variables for your property (optional)

Do you have specific values you'll repeatedly use in the property's rule tree? Use built-in system variablesor create your own and apply them as you need them.

6 - Calculate a domain validation challenge (optional)

Run the POST operation to generate the certificate domain validation challenge ahead of time.

Generate certificate domain validation challenges
Open Recipe

The response includes the validationCname object you use to create a new CNAME record your DNS and map the hostname to the target. You can then skip steps 8 and 9.

7 - Set up property hostnames

Here, you map your property hostnames to an edge hostname, so that the edge servers can take over the client traffic from your origin. With Default DV, you specify "certificateProvisioningType": "DEFAULT" using this API operation to have Property Manager automatically secure your HTTPS delivery and create an edge hostname upon activation:

Update a property with a Default DV certificate hostname
Open Recipe

🚧

You can provision up to 50 Default DV certificates per hour. If you exceed that limit, PAPI automatically queues and processes the remaining certificates in the next batch.

8 - Get the hostname certificate validation challenge

Run this operation and locate your hostname, based on its "cnameFrom": "<your domain>". It should also include "certProvisioningType": "DEFAULT".

List hostnames for a property
Open Recipe

Review these values in the response:

  • cnameFrom. Confirm that this is the correct domain for your site or resource.
  • validationCname. Store the hostname and target values from this object.

9 - Add the validation challenge to your DNS

If you haven't calculated validation challenges in advance in step 6, in your DNS configuration, create a CNAME record and map the hostname to the target you stored in step 8.

10 - Confirm the hostname certificate deployment

Re-run this operation to check status. If it's still PENDING, check again later.

List hostnames for a property
Open Recipe

11 - Get the rule tree

Get the baseline of your property's rule tree. It includes all of the default rules and behaviors that ​Akamai​ adds. What you'll get in the response varies depending on your ​Akamai​ product.

Get a property rule tree
Open Recipe

12 - Edit the rule tree

Provide necessary details for the top-level default rule. At a minimum, configure these mandatory behaviors in a rule:

You can optionally include any number of your own rules to customize content delivery. Rule trees are maintained in a special form of JSON that you can best edit and validate in the dedicated VS code or Eclipse IDE plugins.

13 - Validate the rule tree changes

Make sure your JSON file is correct and complete before deploying it on edge servers. You need to resolve returned errors, as they block an activation, but you can activate a property version that yields less severe warnings. For more information, see Rule tree errors and warnings. Both VS code and Eclipse plugins support full rule tree validation.

14 - Update the property's rule tree

Push your updated JSON file back to the property.

Update a rule tree
Open Recipe

15 - Activate the property on staging and production

With brand new setups, you only need to test your configuration on production. But, you can activate your property on both networks at the same time.

Activate a property version
Open Recipe

16 - Confirm activation

Make sure the activation was successful. The response should contain "status": ACTIVE.

List activations
Open Recipe

17 - Check the hostname certificate again

After activation, your certificate should be in the DEPLOYED status.

List hostnames for a property
Open Recipe

18 - Test the activated settings

Temporarily set up your local browser to target an edge server to access your property.

  1. You need your edge hostname's actual IP address. Get it by running a command for your stored edge hostname. For example, assume the domain you set in your edge hostname was "example.com" and you're using a Standard TLS certificate that adds the edgesuite.net suffix to your hostname behind the scenes:

    Windows:

    nslookup www.example.com.edgesuite.net

    Mac OS, Linux, or Unix:

    dig www.example.com.edgesuite.net

    dig AAAA www.example.com.edgesuite.net

  2. Navigate to your local hosts file in a text editor.

    • Windows. You should be able to find your hosts file in: C:\Windows\System32\drivers\etc\hosts
    • Mac OS, Linux, or Unix. You should be able to find your hosts file in: /etc/hosts

  3. At the end of the hosts file, add an entry for the actual domain to your website that includes the edge hostname's IP address.

    1.23.45.78 example.com

  4. Save and close your hosts file. Restart your browser to clear your DNS cache and verify that your site is working the way you expect.

For more details on testing and activation, see Activate a property.

19 - Go live

Start serving live traffic through the ​Akamai​ Edge Platform. Replace your existing CNAME record and with a new one, setting its value to the ​Akamai​ edge hostname.

Remember to remove any entries from your local hosts file that you may have set up for testing. Now, you can restart your browser and do a smoke test of your website or application.

Configure alerts for your certificates

After you activate the property, you need to set up certificate-related notifications.

🚧

While these alerts are automatically generated for CPS-managed certificates, you need to create them manually for Default DV certificates. Otherwise, you won't receive any notifications about certificate expiration or issues with domain validation.

In ​Control Center​, go to the Alerts application. In the Select alert type field, type these names:

  • Expired Default certificate – this alert notifies you that a Default DV certificate is expired. To make sure it renews automatically, verify your DNS includes the CNAME record with the ACME validation challenge.
  • Expired Default certificate removal – this alert notifies you that an expired Default DV certificate will be removed from the network.
  • DNS does not contain an authorized certificate authority – this alert notifies you when the Default DV certificate cannot be issued because Let’s Encrypt is not an authorized certificate authority in your DNS.
  • Domain validation failed – this alert notifies you when a Default DV certificate cannot be issued because DNS validation failed.
  • Certificate’s domain is blocked – this alert notifies you when a Default DV certificate cannot be issued because the domain is blocked by the certificate authority Let’s Encrypt.

For complete steps, see Create an alert.