Guide
  1. Domain Ownership

Validate domains

📘

Domain validation is mandatory for all newly onboarded domains.

Prove ownership of new domains you onboard to Akamai before activating your property configuration. This prevents unauthorized use of hostnames on the Akamai network, which improves overall security.

What you'll do

Validate new domains and add them to your property. You can validate your domains using one of these two workflows:

  • Pre-validation (recommended) when you validate domains before setting up a property. This covers exact hostname, domain, and wildcard validation scopes.

    Important: Domains managed inside the hostname bucket must be pre-validated.

  • Late-validation when you validate domains after defining them in the property.

What you need

To validate your domains, you need:

  • A property from the Property Manager (PAPI) API.
  • A DNS zone with its records from the Edge DNS API if using the DNS_CNAME or DNS_TXT domain validation method.

Pre-validation

1. Add domains for validation

Initiate the domain validation with the New-DOMDomain command. Each domain you want to validate needs to include its name and the scope within which you want to perform validation. It can be either:

  • HOST. The scope covers only the exactly specified domain.
  • WILDCARD. The scope covers any hostname within one subdomain level.
  • DOMAIN. The scope covers any hostnames under the domain, regardless of the subdomain level.

Save the New-DOMDomain operation in a variable so you can more easily retrieve the challenge data for your domains.

Note: When you pass multiple values to the -DomainName and -ValidationScope parameters, the operation pairs them by position, that is, the first domain name with the first validation scope, the second with the second, and so on. Each pair triggers a separate API call, which is why you see multiple outputs.

$NewDomains = New-DOMDomain -DomainName 'example.com', 'sub.example.com' -ValidationScope 'HOST', 'WILDCARD'

$NewDomains.successes.validationChallenge
cnameRecord    : @{name=_acme-challenge.example.com; target=ac.1ab23c45def678gh9ij01klm23n4op.example.com.validate-akdv.net}
txtRecord      : @{name=_akamai-host-challenge.example.com; value=abcDeFghi12JK-LmNopQr3ST-uVwX4Y_zAbCDEfgijkLmnoPqRstuV5-wXy678Z}
httpFile       : @{path=https://example.com/.well-known/akamai/akamai-challenge/abc1dEf3gh-ij3hlmoPr; 
                 content=abcDeFghi12JK-LmNopQr3ST-uVwX4Y_zAbCDEfgijkLmnoPqRstuV5-wXy678Z; contentType=text/plain}
httpRedirect   : @{from=https://example.com/.well-known/akamai/akamai-challenge/abc1dEf3gh-ij3hlmoPr; 
                 to=https://validation.akamai.com/.well-known/akamai/akamai-challenge/abcDeFghi12JK-LmNopQr3ST-uVwX4Y_zAbCDEfgijkLmnoPqRstuV5-wXy678Z}
expirationDate : 3/13/2026 12:51:03 PM

cnameRecord    : @{name=_acme-challenge.sub.example.com; 
                 target=ac.z9yx87wv654utsrq32ponm10lk987j.sub.example.com.validate-akdv.net}
txtRecord      : @{name=_akamai-wildcard-challenge.sub.example.com; value=yXwyUT98Sr-qPonmLkJi7Hg-FeDC6b_AzywVusTrQpONmlkJ5iHGf-eDc43b}
expirationDate : 3/13/2026 1:27:08 PM

You can also add multiple domains for validation at once by saving them in a variable containing a domains object. It batches all domains into a single API call, which is more efficient. Then pipe the variable to the New-DOMDomain operation or pass it in the -Body parameter.

$MyDomains = @{
    domains = @(
        @{
            validationScope = "HOST"
            domainName      = "example.com"
        }
        @{
            validationScope = "WILDCARD"
            domainName      = "sub.example.com"
        }
    )
}

$MyDomains | New-DOMDomain
successes
---------                                                                                                                                  
{@{accountId=A-CCT1234; domainName=example.com; validationScope=HOST; domainStatus=REQUEST_ACCEPTED; validationReques…

After adding a domain to track it for validation, its initial status is REQUEST_ACCEPTED.

The operation returns the challenge data for a domain. You need to complete the validation process in the time frame specified by the challenge data's expiry date.

Once the challenge data expires, the domain is marked with the TOKEN_EXPIRED status. You can resubmit the domain to generate new challenge data and validate the domain. Once a validation is completed, it doesn’t expire, and you don’t need to revalidate the domain.

2. Update your DNS or HTTP server

Depending on the validation method you want to apply, either DNS_CNAME, DNS_TXT, or HTTP, use the domain's challenge details returned from the New-DOMDomain operation to update your DNS configuration or HTTP server.

The New-EDNSRecordSet operation used to add new DNS records doesn't return any output.

DNS CNAME

For the DNS_CNAME domain validation method:

  1. Using the New-EDNSRecordSet operation, add a CNAME record to your DNS configuration in the _acme-challenge.domain-name format within the -Name parameter.

    For example, for a domain called example.com, the record's name should be _acme-challenge.example.com.

    You can also reference this value from New-DOMDomain as $NewDomains.successes[<domain_index>].validationChallenge.cnameRecord.name.

  2. Copy a given domain's validationChallenge.cnameRecord.target attribute value returned to you in the New-DOMDomain operation's response or reference if from New-DOMDomain as $NewDomains.successes[<domain_index>].validationChallenge.cnameRecord.target. Then paste it to the -RData parameter.

    # With direct values
New-EDNSRecordSet -Zone 'example.com' -Name '_acme-challenge.example.com' -Type 'CNAME' -TTL 1800 -RData 'ac.ab12c3defg45hijk678lmn9o.example.com.validate-akdv.net'

# With referenced values
New-EDNSRecordSet -Zone 'example.com' -Name $NewDomains.successes[0].validationChallenge.cnameRecord.name -Type 'CNAME' -TTL 1800 -RData $NewDomains.successes[0].validationChallenge.cnameRecord.target

DNS TXT

For the DNS_TXT domain validation method:

  1. Using the New-EDNSRecordSet operation, add a TXT record to your DNS configuration in the _akamai-{host|wildcard|domain}-challenge.domain-name format within the -Name parameter. Include the host, wildcard, or domain part, depending on the validation scope of your domain.

    For example, for a domain called example.com and the HOST validation scope, the record's name should be _akamai-host-challenge.example.com.

    You can also reference this value from New-DOMDomain as $NewDomains.successes[<domain_index>].validationChallenge.txtRecord.name.

  2. Copy a given domain's validationChallenge.txtRecord.value attribute value returned to you in the New-DOMDomain operation's response or reference if from New-DOMDomain as $NewDomains.successes[<domain_index>].validationChallenge.txtRecord.value. Then paste it to the -RData parameter.

    # With direct values
New-EDNSRecordSet -Zone 'example.com' -Name '_akamai-host-challenge.example.com' -Type 'TXT' -TTL 3600 -RData 'aB1cDE2f3G4h5iJKl67MnopQrs8tUwxY9'

# With referenced values
New-EDNSRecordSet -Zone 'example.com' -Name $NewDomains.successes[0].validationChallenge.txtRecord.name -Type 'TXT' -TTL 3600 -RData $NewDomains.successes[0].validationChallenge.txtRecord.value

HTTP

It applies only to domains with the HOST validation scope. For the HTTP domain validation method:

  1. Create a file and paste a given domain's $NewDomains.successes[<domain_index>].validationChallenge.httpFile.content attribute value returned to you in the New-DOMDomain operation's response.

  2. Place the file on your HTTP server in the location specified by the domain's $NewDomains.successes[<domain_index>].validationChallenge.httpFile.path attribute value that you can find in the New-DOMDomain operation's response. The last part of the URL must be the file name.

    Alternatively, you can use a redirect to the domain's $NewDomains.successes[<domain_index>].validationChallenge.httpRedirect.to attribute value from the New-DOMDomain operation's response. For example, https://validation.akamai.com/.well-known/akamai/akamai-challenge/<your-challenge-data>.

3. Validate domains

Use the Complete-DOMDomain operation to validate your domains immediately after updating your DNS configuration or HTTP server. In the operation, specify the domain's name, validation scope, and validation method.

Note: This operation pairs multiple -DomainName and -ValidationScope values by position, the same way as New-DOMDomain. Each pair triggers a separate API call.

You get an error if you try to run this operation on domains that have already been validated.

Complete-DOMDomain -DomainName 'example.com', 'sub.example.com' -ValidationScope 'HOST', 'WILDCARD' -ValidationMethod 'DNS_CNAME'
DomainName      domainStatus           validationScope
----------      ------------           ---------------
example.com     VALIDATION_IN_PROGRESS HOST
sub.example.com VALIDATION_IN_PROGRESS WILDCARD

This skips the standard schedule of DOM background jobs (crons) and validates the domain straight away or after a short delay, depending on the number of requests in the queue.

If the initial validation attempt fails, often because the challenge data wasn't set up correctly, your domains remain in the VALIDATION_IN_PROGRESS status.

To check the validation statuses of your domains, run:

Get-DOMDomain -DomainName 'example.com' -ValidationScope 'HOST'

Find-DOMDomain -DomainName 'example.com', 'sub.example.com' -ValidationScope 'HOST', 'WILDCARD'
accountId               : A-CCT1234
domainName              : example.com
validationScope         : HOST
domainStatus            : VALIDATED
validationMethod        : DNS_CNAME
validationRequestedBy   : jsmith
validationRequestedDate : 1/12/2026 8:54:42 AM
validationCompletedDate : 1/12/2026 9:00:15 AM
validationChallenge     : @{cnameRecord=; txtRecord=; httpFile=; httpRedirect=; expirationDate=1/26/2026 8:54:42 AM}
domainStatusHistory     : {}
domainName      validationScope domainStatus           validationLevel
----------      --------------- ------------           ---------------
sub.example.com WILDCARD        VALIDATION_IN_PROGRESS FQDN
example.com     HOST            VALIDATED              FQDN

4. Add a hostname to a property version

Once your domain is validated, add it to your property.

  1. Create a new inactive, editable property version with the New-PropertyVersion operation.

    New-PropertyVersion -PropertyName MyProperty -CreateFromVersion 'latest'
     propertyLink                                                              propertyVersion
 ------------                                                              ---------------
 /papi/v1/properties/12345/versions/11?contractId=C-0N7RAC7&groupId=12345           latest

    The output contains a link to your property's new version and the property's version number.

  2. Use the new property version to add your hostname with the Add-PropertyHostname operation.

    $MyHostnames = @(
    @{
        certProvisioningType = "DEFAULT"
        cnameFrom = "example.com"
        cnameTo = "example.com.edgekey.net"
    }
)

Add-PropertyHostname -PropertyName 'my-property' -PropertyVersion 'latest' -NewHostnames $MyHostnames -GroupID 12345 -ContractId 'C-0N7RAC7'
    cnameType            : EDGE_HOSTNAME
edgeHostnameId       : ehn_12345
cnameFrom            : example.com
cnameTo              : example.com.edgekey.net
certProvisioningType : DEFAULT

Late-validation

As you build out your property, DNS, and hostname configurations or make updates to them, the validation state of your domains could vary.

This happens when you're still working on a configuration and haven't validated all of your property's hostnames, or you add more hostnames to a new property version.

You can't activate a property without validation of all its hostnames.

  1. When you add a new non-validated hostname to a property with Add-PropertyHostname, the challenge data for that hostname is auto-generated. You can find that data in the operation's output within the domainOwnershipVerification attribute.

     $MyHostnames = @(
     @{
         certProvisioningType = "DEFAULT"
         cnameFrom = "example-other.com"
         cnameTo = "example-other.com.edgekey.net"
     }
 )

 Add-PropertyHostname -PropertyName 'my-property' -PropertyVersion 'latest' -NewHostnames $MyHostnames -GroupID 12345 -ContractId 'C-0N7RAC7'
    cnameType                   : EDGE_HOSTNAME
edgeHostnameId              : ehn_98765
cnameFrom                   : example-other.com
cnameTo                     : example-other.com.edgekey.net
certProvisioningType        : DEFAULT
domainOwnershipVerification : @{status=REQUEST_ACCEPTED; challengeTokenExpiryDate=3/17/2026 11:56:08 AM; 
                          validationCname=; validationTxt=; validationHttp=}

  2. Depending on the validation method you want to apply, update your DNS or HTTP server using the challenge data returned from Add-PropertyHostname.

  3. Once you've updated your DNS configuration or HTTP server, validate your domains.

Activate your property

After validating your domains using the pre- or late-validation flow, activate your property to apply its settings to your site and its traffic. Using the New-PropertyActivation command or its alias Deploy-Property, specify the network of activation, STAGING or PRODUCTION, and the version you want to activate.

Deploy-Property -PropertyName 'my-property' -PropertyVersion 'latest' -Network 'Staging' -NotifyEmails 'jsmith@email.com'
activationLink                                                                                      activationId
--------------                                                                                      ------------
/papi/v1/properties/prp_12345/activations/atv_67890?contractId=ctr_C-0N7RAC7&groupId=grp_12345      atv_67890

Other actions

Invalidate a domain

If you lose ownership of a domain or deactivate a property, you can invalidate the domain with the Disable-DOMDomain operation.

Disable-DOMDomain -DomainName 'example.com' -ValidationScope 'HOST'
domainName      validationScope domainStatus
----------      --------------- ------------
example.com     HOST            INVALIDATED

To retrieve the invalidated domain:

  1. Re-add it with the New-DOMDomain operation.
  2. Set up new challenge data via a DNS or HTTP server.
  3. Resubmit it for validation with the Complete-DOMDomain operation.

Delete a domain

If the domain is in the VALIDATED status and you want to remove it, first invalidate the domain.

Remove-DOMDomain -DomainName 'example.com' -ValidationScope 'HOST'

The operation doesn't return any output.

If you want to use the deleted domain again:

  1. Re-add it with the New-DOMDomain operation.
  2. Set up new challenge data via a DNS or HTTP server.
  3. Resubmit it for validation with the Complete-DOMDomain operation.

Updated about 1 hour ago