/Docs
View Markdown Sign in
For the full documentation index, see PageWeave Documentation or fetch llms.txt.

OAuth Setup

PageWeave acts as an OAuth 2.1 Authorization Server for MCP clients.

Discovery Endpoints

Endpoint RFC Purpose
GET /.well-known/oauth-authorization-server RFC 8414 Authorization server metadata
GET /.well-known/oauth-protected-resource RFC 9728 Protected resource metadata
GET /.well-known/openid-configuration OIDC Discovery OIDC-compatible discovery
POST /oauth/register RFC 7591 Dynamic client registration

OAuth Flow

  1. Client fetches /.well-known/oauth-protected-resource
  2. Client fetches /.well-known/oauth-authorization-server
  3. Client registers via POST /oauth/register
  4. Client redirects user to /oauth/authorize with PKCE code_challenge
  5. User signs in and grants access
  6. Client exchanges code for token at POST /oauth/token
  7. Client calls POST /mcp with Authorization: Bearer <token>

Scopes

34 resource-based scopes control MCP tool access:

Resource Scopes
website :read, :create, :edit, :delete
page :read, :create, :edit, :delete
header :read, :edit
footer :read, :edit
html_head :read, :edit
theme :read, :edit
asset :read, :create, :delete
form :read, :create, :edit, :delete
table :read, :create, :edit, :delete
row :read, :create, :edit, :delete
submission :read, :delete
webhook :read, :create, :edit, :delete
domain :read, :create, :delete
dns :read, :write
access :read, :delete
invitation :read, :create, :delete
analytics :read
version :read, :pin, :unpin, :revert
preview :read, :start, :stop

Default scopes for new clients: all *:read scopes. Write scopes must be explicitly requested.

Token Lifetime

OAuth tokens expire after 1 hour. Clients should refresh tokens before expiration.

Client Setup

All modern MCP clients support automatic OAuth 2.1 discovery and authentication. Add the MCP endpoint URL and the client handles the rest.

Minimal Configs

Client Config File Minimal Config Docs
OpenCode opencode.json {"type": "remote", "url": "https://pageweave.dev/mcp", "enabled": true, "oauth": {}} OpenCode MCP Docs ↗
Claude Code .mcp.json {"type": "http", "url": "https://pageweave.dev/mcp"} Claude Code MCP Docs ↗
Claude Desktop claude_desktop_config.json {"command": "npx", "args": ["-y", "mcp-remote", "https://pageweave.dev/mcp"]} Claude Desktop Auth Docs ↗
Cursor .cursor/mcp.json {"url": "https://pageweave.dev/mcp"} Cursor MCP Docs ↗
Windsurf mcp_config.json {"serverUrl": "https://pageweave.dev/mcp"} Windsurf MCP Docs ↗
Continue config.yaml type: streamable-httpurl: https://pageweave.dev/mcp Continue MCP Docs ↗

What Happens Automatically

  1. Discovery — Client detects the 401 challenge and fetches /.well-known/oauth-protected-resource
  2. Registration — Client registers dynamically via POST /oauth/register (RFC 7591)
  3. Authorization — Client opens your browser to /oauth/authorize with PKCE
  4. Token exchange — Client exchanges the authorization code for tokens
  5. Storage & refresh — Tokens are stored securely and refreshed automatically

No manual token management required.

API Key Fallback

For programmatic access or legacy clients, authenticate with API keys (pagew_...) via Authorization: Bearer <key>. API keys bypass all scope checks and provide full access. Best for CI/CD and server-to-server use.