monorepo/cloud/maplepress-backend/docs/API/verify-site.md

Verify WordPress Site

POST /api/v1/sites/{id}/verify

Verify a WordPress site by checking DNS TXT records to prove domain ownership. This transitions the site from pending to active status.

Authentication: Required (JWT Bearer token)

Headers:

• Authorization: JWT {access_token}

URL Parameters:

Parameter	Type	Required	Description
id	UUID	Yes	Site ID

Request Body:

No request body required. Verification is done automatically by checking DNS TXT records.

DNS TXT Record Setup:

Before calling this endpoint, you must add a DNS TXT record to your domain:

Field	Value
Host/Name	Your domain (e.g., example.com)
Type	TXT
Value	maplepress-verify={verification_token}

The verification token is provided when you create the site. DNS propagation typically takes 5-10 minutes but can take up to 48 hours.

Example Request:

curl -X POST http://localhost:8000/api/v1/sites/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Example Response (200 OK):

{
  "success": true,
  "status": "active",
  "message": "Domain ownership verified successfully via DNS TXT record"
}

Important Notes:

• The verification token is provided when the site is created (POST /api/v1/sites)
• You must add the DNS TXT record to your domain before calling this endpoint
• DNS propagation typically takes 5-10 minutes but can take up to 48 hours
• Once verified, the site status changes from pending to active
• After verification, the site can sync pages and use search functionality
• Test mode sites (test_sk_ API keys) skip DNS verification automatically
• Already verified sites return success without error

Verification Flow:

1. User creates site via dashboard → receives verification_token and DNS instructions
2. User adds DNS TXT record to domain registrar: maplepress-verify={token}
3. User waits 5-10 minutes for DNS propagation
4. User clicks "Verify Site" in plugin → calls this endpoint
5. Backend performs DNS TXT lookup to verify domain ownership
6. Site transitions to active status → full functionality enabled

Error Responses:

This endpoint returns errors in RFC 9457 (Problem Details for HTTP APIs) format.

Content-Type: application/problem+json

400 Bad Request - DNS TXT record not found:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "DNS TXT record not found. Please add the verification record to your domain's DNS settings and wait 5-10 minutes for propagation."
}

400 Bad Request - DNS lookup timed out:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "DNS lookup timed out. Please check that your domain's DNS is properly configured."
}

400 Bad Request - Domain not found:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Domain not found. Please check that your domain is properly registered and DNS is active."
}

400 Bad Request - Invalid site ID:

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid site ID format. Please provide a valid site ID."
}

401 Unauthorized - Missing or invalid JWT:

{
  "type": "about:blank",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Tenant context is required to access this resource."
}

404 Not Found - Site not found or doesn't belong to tenant:

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "The requested site could not be found. It may have been deleted or you may not have access to it."
}

500 Internal Server Error - Server error:

{
  "type": "about:blank",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "Failed to verify site. Please try again later."
}

Related Endpoints:

• Create Site - Initial site creation (provides verification token)
• Get Site - Check verification status
• Plugin Status - Check verification status from plugin
• Sync Pages - Requires verification