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

cloud/maplepress-backend/docs/API/rotate-site-api-key.md

@@ -0,0 +1,79 @@
+# Rotate Site API Key
+
+**POST /api/v1/sites/{id}/rotate-api-key**
+
+Rotate a site's API key (use when the key is compromised).
+
+**Authentication**: Required (JWT Bearer token)
+
+**Headers**:
+- `Authorization: JWT {access_token}`
+
+**URL Parameters**:
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| id | UUID | Yes | Site ID |
+
+**Example Request**:
+
+```bash
+curl -X POST http://localhost:8000/api/v1/sites/a1b2c3d4-e5f6-7890-abcd-ef1234567890/rotate-api-key \
+  -H "Authorization: JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+```
+
+**Example Response** (200 OK):
+
+```json
+{
+  "new_api_key": "live_sk_z9y8x7w6v5u4t3s2r1q0p9o8n7m6l5k4j3i2h1g0",
+  "old_key_last_four": "s9t0",
+  "rotated_at": "2024-10-27T15:00:00Z"
+}
+```
+
+**🚨 CRITICAL Notes**:
+- The `new_api_key` is shown **only once** - save it immediately!
+- The old API key is **immediately invalidated** - no grace period!
+- Your WordPress site will stop working until you update the plugin with the new key
+- Update the WordPress plugin settings **RIGHT NOW** to restore functionality
+- The rotation happens atomically:
+  - Old key is deleted from the database
+  - New key is inserted into the database
+  - Both operations complete instantly
+
+**Error Responses**:
+
+This endpoint returns errors in **RFC 9457 (Problem Details for HTTP APIs)** format.
+
+**Content-Type**: `application/problem+json`
+
+**401 Unauthorized**:
+```json
+{
+  "type": "about:blank",
+  "title": "Unauthorized",
+  "status": 401,
+  "detail": "Authentication required"
+}
+```
+
+**404 Not Found**:
+```json
+{
+  "type": "about:blank",
+  "title": "Not Found",
+  "status": 404,
+  "detail": "Site not found or doesn't belong to your tenant"
+}
+```
+
+**500 Internal Server Error**:
+```json
+{
+  "type": "about:blank",
+  "title": "Internal Server Error",
+  "status": 500,
+  "detail": "Failed to rotate API key"
+}
+```