Initial commit: Open sourcing all of the Maple Open Technologies code.

2025-12-02 14:33:08 -05:00 · 2025-12-02 14:33:08 -05:00 · 755d54a99d
commit 755d54a99d
2010 changed files with 448675 additions and 0 deletions
--- a/cloud/maplepress-backend/docs/API/verify-site.md
+++ b/cloud/maplepress-backend/docs/API/verify-site.md
@ -0,0 +1,148 @@
+# 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**:
+
+```bash
+curl -X POST http://localhost:8000/api/v1/sites/a1b2c3d4-e5f6-7890-abcd-ef1234567890/verify \
+  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+```
+
+**Example Response** (200 OK):
+
+```json
+{
+  "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:
+```json
+{
+  "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:
+```json
+{
+  "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:
+```json
+{
+  "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:
+```json
+{
+  "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:
+```json
+{
+  "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:
+```json
+{
+  "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:
+```json
+{
+  "type": "about:blank",
+  "title": "Internal Server Error",
+  "status": 500,
+  "detail": "Failed to verify site. Please try again later."
+}
+```
+
+**Related Endpoints**:
+- [Create Site](./create-site.md) - Initial site creation (provides verification token)
+- [Get Site](./get-site.md) - Check verification status
+- [Plugin Status](./plugin-verify-api-key.md) - Check verification status from plugin
+- [Sync Pages](./plugin-sync-pages.md) - Requires verification