148 lines
4.2 KiB
Markdown
148 lines
4.2 KiB
Markdown
# 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
|