API keys

API keys authenticate requests to the Power MCP service. Every MCP tool call requires a valid wpe_ key in the Authorization: Bearer header.

Key types

The MCP server recognizes two key types, distinguished by whether they’re bound to a minting user:

Type	Identity	Scope	Can run abilities	Use case
Personal	Minting user’s Okta sub	Project + acting user	✓	Interactive MCP clients (Claude Code CLI)
Project	None (project-scoped service credential)	Project only	✗	Service-to-service, read-only automation

Personal keys are required for WordPress ability execution (list_site_abilities, run_site_ability) because they resolve an acting user for the WordPress account connection check. Project keys work for navigation tools (ping, list_account_sites) but cannot execute abilities.

Create a personal API key

1. Sign in to the Power console
2. Select your project
3. Go to API keys → Create key
4. Choose Personal key as the key type
5. Choose Restricted permissions and set MCP to Write (or use “All permissions” for testing)
6. Copy the key value — it’s shown once

The key format is wpe_<base64url-encoded-secret>. Store it securely; the Power console never re-displays it.

Permissions and scopes

Keys carry a permission set that gates which API operations they can reach. For the MCP server, the key must have:

• mcp: write — Required for all MCP tools
• OR all — Grants access to all API operations (use for testing)

Restricted keys without mcp: write return 403 Forbidden when calling MCP tools.

Key scope (account vs project)

Credential	Account scope	Project scope	Sites visible
Personal API key	Derived from project	Pinned to project	Sites in the key’s project
Project API key	Derived from project	Pinned to project	Sites in the key’s project
OAuth token (future)	User-selected	All projects	All sites in the account

API keys are project-scoped: list_account_sites returns only registrations in the key’s project and defaults to status: active. Pass status: revoked or status: suspended to select that exact lifecycle state instead. Sites with project_id: null (registered before project assignment) are invisible to API keys and will only surface via OAuth (account-scoped) sessions.

Personal key identity binding

A personal key’s owner_subject field stores the Okta sub of the minting user. This is the identity used for:

• WordPress account connection checks — run_site_ability verifies the owner_subject has an active wp_user_connections row for the target site
• wp_connection_status in list_account_sites — each site reports whether this user is connected
• Audit logs — the acting user for ability executions

Project keys have owner_subject: null and resolve no acting user, so they can never satisfy that check.

Use in MCP clients

Claude Code CLI

Add the server with your API key:

claude mcp add --transport http coworker \
  https://api.ai.wpengine.com/v1/mcp \
  --header "Authorization: Bearer wpe_abc123..."

Replace wpe_abc123... with your actual API key. No restart needed.

Claude Desktop

Claude Desktop’s config file is stdio-only. Use the mcp-remote bridge:

{
  "mcpServers": {
    "coworker": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@0.1.38",
        "https://api.ai.wpengine.com/v1/mcp",
        "--header",
        "Authorization: Bearer wpe_abc123..."
      ]
    }
  }
}

See Configure Claude Desktop for paths and restart notes.

MCP Inspector

Pass the key via the --header flag:

npx @modelcontextprotocol/inspector \
  --cli https://api.ai.wpengine.com/v1/mcp \
  --transport http \
  --header "Authorization: Bearer wpe_abc123..." \
  --method tools/list

Custom clients

Send the key in the Authorization header on every request:

POST /v1/mcp HTTP/1.1
Host: api.ai.wpengine.com
Authorization: Bearer wpe_abc123...
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}

Rotate a key

To replace a compromised or expiring key:

1. Create a new key in the Power console (same type and permissions)
2. Update your MCP client configuration with the new key
3. Test the connection (ping tool)
4. Revoke the old key from the Power console

Key rotation is seamless: the new key works immediately; the old key stops working once revoked.

Revoke a key

Revoked keys return 401 Unauthorized on all requests. To revoke:

1. Go to API keys in the Power console
2. Find the key to revoke
3. Click Revoke
4. Confirm

Revocation is immediate and irreversible.

Key format and validation

Valid API keys:

• Start with wpe_
• Contain only base64url characters (A-Za-z0-9_-)
• Are 40–100 characters total

Invalid formats return 401 Unauthorized immediately, before reaching the MCP server.

Security best practices

• Never commit keys to version control — use environment variables or secret managers
• Use personal keys for humans, project keys for services — keeps audit trails clear
• Rotate keys quarterly — reduces blast radius of leaks
• Revoke unused keys immediately — minimize active credential surface
• Store keys encrypted — password managers, CI secret stores, or OS keychains

Errors

Invalid key format

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": "invalid_token",
  "error_description": "API key must start with wpe_"
}

Solution: Verify the key format and re-copy from the Power console.

Revoked key

HTTP/1.1 401 Unauthorized

{
  "error": "invalid_token",
  "error_description": "API key has been revoked"
}

Solution: Create a new key and update your configuration.

Missing MCP permission

HTTP/1.1 403 Forbidden

{
  "error": {
    "message": "API key does not have 'write' permission for scope 'mcp' (granted: 'none').",
    "type": "permission_error",
    "code": 403,
    "request_id": "req_..."
  }
}

Solution: Create a new key with mcp: write or all permissions.

Next steps

• Configure Claude Code — Add the MCP server to your CLI
• Getting started tutorial — Complete the full setup flow
• Site and WordPress account connections — Understand authorization model