SOP: API Integration

Fresh

Setting up REST API and Abilities API access for your MainWP Dashboard.

Prerequisites

• [ ] MainWP Dashboard 5.0+ (REST API) or 6.0+ (Abilities API)
• [ ] WordPress admin account
• [ ] HTTPS enabled on Dashboard

Option A: REST API v2 Setup

Step 1: Generate API Keys

Dashboard → MainWP → Settings → REST API → Add New API Key
  - Description: "My Integration"
  - Permissions: Read / Write / Read+Write
  → Generate

Save both the Consumer Key and Consumer Secret immediately — the secret is shown only once.

Step 2: Test Connection

# Test authentication
curl -H "Authorization: Bearer YOUR_CONSUMER_KEY" \
  "https://your-dashboard.com/wp-json/mainwp/v2/sites"

Expected: JSON array of sites (or empty array if no sites).

Step 3: Make Your First API Call

# List all sites
curl -H "Authorization: Bearer YOUR_CONSUMER_KEY" \
  "https://your-dashboard.com/wp-json/mainwp/v2/sites"

# Get a specific site
curl -H "Authorization: Bearer YOUR_CONSUMER_KEY" \
  "https://your-dashboard.com/wp-json/mainwp/v2/sites/123"

Option B: Abilities API Setup (WordPress 6.9+)

Step 1: Create Application Password

Dashboard → Users → Your Profile → Application Passwords
  - Name: "MainWP Abilities"
  → Add New Application Password

Save the generated password immediately — it's shown only once.

Step 2: Test Connection

# Verify authentication
curl -u "username:app-password" \
  "https://your-dashboard.com/wp-json/wp/v2/users/me"

# List available abilities
curl -u "username:app-password" \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities?per_page=5"

Step 3: Execute an Ability

# List sites via Abilities API
curl -u "username:app-password" \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/list-sites-v1/run"

Option C: MCP Server Setup

For Claude Code

claude mcp add --transport stdio mainwp \
  --env MAINWP_URL=https://your-dashboard.com \
  --env MAINWP_USER=admin \
  --env MAINWP_APP_PASSWORD="xxxx xxxx xxxx xxxx" \
  -- npx -y @mainwp/mcp

For Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "mainwp": {
      "command": "npx",
      "args": ["-y", "@mainwp/mcp"],
      "env": {
        "MAINWP_URL": "https://your-dashboard.com",
        "MAINWP_USER": "admin",
        "MAINWP_APP_PASSWORD": "xxxx xxxx xxxx xxxx"
      }
    }
  }
}

For VS Code Copilot

Add to .vscode/mcp.json:

{
  "servers": {
    "mainwp": {
      "command": "npx",
      "args": ["-y", "@mainwp/mcp"],
      "env": {
        "MAINWP_URL": "https://your-dashboard.com",
        "MAINWP_USER": "admin",
        "MAINWP_APP_PASSWORD": "xxxx xxxx xxxx xxxx"
      }
    }
  }
}

API Comparison

Feature	REST API v2	Abilities API	MCP Server
Auth	API Key (Bearer)	Application Password (Basic)	Application Password (env)
WordPress Required	5.0+	6.9+	6.0+ (Dashboard)
MainWP Required	5.0+	6.0+	6.0+
Endpoints	Resource-based REST	Ability-based RPC	64 MCP tools
Safety Controls	None built-in	Confirmation + Safe Mode	Confirmation + Safe Mode
Batch Support	Limited	Automatic (>200 sites)	Via abilities
Best For	Custom integrations	AI/LLM clients	Claude, Cursor, Copilot

Security Best Practices

1. Use HTTPS — never send credentials over HTTP
2. Limit permissions — use read-only keys when possible
3. Rotate credentials — change keys/passwords periodically
4. IP restrictions — restrict API access by IP if possible
5. Monitor access — review API logs regularly
6. Separate credentials — use different keys for different integrations
7. Enable Safe Mode for MCP — MAINWP_SAFE_MODE=true blocks destructive ops

Verification

• [ ] Authentication works (200 response on test endpoint)
• [ ] Can list sites
• [ ] Can read site details
• [ ] Can perform write operations (if needed)
• [ ] Rate limits are acceptable
• [ ] Error handling is in place

Troubleshooting

Issue	Fix
401 Unauthorized	Check credentials, regenerate if needed
403 Forbidden	User needs admin capabilities
404 Not Found	Check URL path, verify API is enabled
CORS errors	Add CORS headers or use server-side requests
Rate limited	Reduce request frequency, implement backoff