API workflow

Follow this workflow to validate your domain with the DOM API.

1. Submit domains for validation.

   • In the request body, include the names of the domains you’re adding, together with the requested validation scope, either HOST, WILDCARD, or DOMAIN.

   Scope	What it covers
   HOST (www.example.com)	Only the domain specified.
   WILDCARD (example.com)	Any hostname within one level of the wildcard. a.example.com is covered. b.a.example.com is not covered. example.com is not covered.
   DOMAIN (example.com)	Any hostnames under the domain, regardless of the level of subdomains. example.com, a.example.com and a.b.example.com are covered.

   • Request body example:

     JSON

     {
       "domains": [
         {
           "domainName": "example.com",
           "validationScope": "HOST"
         },
         {
           "domainName": "example2.com",
           "validationScope": "WILDCARD"
         },
         {
           "domainName": "sample.com",
           "validationScope": "DOMAIN"
         }
       ]
     }
     
     

2. Copy the validation details from the validationChallenge section of the response:

   • dnsCname. DNS CNAME you need to use for DNS CNAME domain validation.
   • challengeToken. Challenge token you need to use for domain validation.
   • challengeTokenExpiresDate. Date and time when the challenge token expires.
   • httpRedirectFrom. HTTP URL for checking the challenge token during HTTP validation.
   • httpRedirectTo. HTTP redirect URL for HTTP validation.

3. Update your DNS or an HTTP server, depending on your preferred validation method:

   • For the DNS_CNAME method:
     • In your DNS configuration, add a CNAME record: _acme-challenge.domainName. For a domain called example.com, the record should be _acme-challenge.example.com.
     • Paste the dnsCname value from the API response as the target.
   • For the DNS_TXT method:
     • In your DNS configuration, add a TXT record: _akamai-{host|wildcard|domain}-challenge.domainName. Include the host, wildcard or domain part, depending on the validation scope of your domain. For a domain called example.com and the DOMAIN validation scope, the record should be: _akamai-domain-challenge.example.com.
     • Add the challengeToken you copied from the API response. The format can be either “token=1234….5678” or “1234….5678”.
   • For the HTTP method:
     • Create a file and paste the challengeToken value as the file contents.
     • Place the file on your HTTP server, in the location given as the httpRedirectFrom in the API response. The last part of the URL must be the file name:

       cd <web-server-www-root>
       mkdirs /.well-known/akamai/akamai-challenge
       echo -n "your-verification-token" > /web-server/.well-known/akamai/akamai-challenge/<challenge-path-token>
       

     • Alternatively, you can use a redirect to the httpRedirectTo with the challenge token.

4. Check the domain status to monitor the validation progress. You can either get a single domain to view its status or list all domains with their statuses. Possible statuses are:

   • REQUEST_ACCEPTED. The initial status of successfully added domains. Validation will start shortly.
   • VALIDATION_IN_PROGRESS. DOM background jobs are now trying to validate the domain.
   • VALIDATED. The domain validation was successful. ​Akamai​ now recognizes you as the domain owner.
   • TOKEN_EXPIRED. You haven't completed the validation in the requested time frame and now the validation token is not valid any more. Add your domain again to get a new token.
   • INVALIDATED. The domain was invalidated and ​Akamai​ doesn't recognize you as its owner. The domain will be automatically deleted as part of a cleanup procedure or you can delete it manually to remove it.

5. You can request to validate your domains immediately , to skip the standard queue of DOM background jobs.