Adding and Verifying Domains

This guide explains how to add and verify a domain for your environment using the WP Engine Hosting API. To ensure platform security, all root domains must be verified via a DNS TXT record before traffic can be routed to your site.

Steps

1. Adding the domain to your environment

Use the POST /installs/{install_id}/domains endpoint to add the domain to your environment.

The API response provides the necessary DNS configuration and verification details:

• txt_verification_key: The “name” or “host” for your TXT record.
• txt_verification_value: The “value” or “content” for your TXT record.
• cname: The CNAME target for your domain.
• a_record: The IP address for your A record.
• ownership_status: This will initially return TXT_VERIFICATION_PENDING.

2. Update your DNS records

At your domain registrar (e.g., GoDaddy, Namecheap, etc.), add the records provided in the previous step:

• TXT Record: Add a TXT record using the txt_verification_key for the Host/Name field and the txt_verification_value for the Value field.
• Routing Record: Add your CNAME (recommended) or A record as provided in the API response.

Note

TXT verification is only required for root domains. Sub-domains do not require separate verification once the root domain is verified.

3. Trigger the verification check

Once the DNS records are saved, you must manually instruct WP Engine to look for them and move the domain out of the “unverified” state.

Use the POST /installs/{install_id}/domains/{domain_id}/verification endpoint to trigger this check.

4. Verify the activation status

The verification process typically completes within a few minutes. To confirm the domain is ready, use the GET /installs/{install_id}/domains/{domain_id} endpoint and check for the following values:

• ownership_status: Should now return TXT_VERIFIED.
• txt_verified_time: Indicates the exact timestamp the verification handshake was completed.
• txt_verified_domain: Confirms the specific domain successfully verified by the system.

Once verified, traffic will begin routing automatically. If this domain was designated as the Primary Domain, that change will now take effect.

Tip

If you need to retrieve your verification keys or check your DNS targets at a later time, you can call the GET domain endpoint or visit the Domains page in the WP Engine User Portal.