Auth Model

PostMCP uses two auth paths: Clerk for browser sessions and scoped API keys for agent, CLI, MCP, OpenClaw, CI, and server workflows.

Browser Sessions

Dashboard users sign in through Clerk. The dashboard sends the Clerk session token to the API, which maps the Clerk user or organization to a PostMCP workspace membership before returning workspace data. You only see workspaces where you are a member.

Personal and Organization Workspaces

PostMCP supports both workspace shapes:

• A personal workspace for each Clerk user who joins without an active Clerk Organization.
• Clerk Organizations for team workspaces — when you invite teammates through Clerk, they share the matching PostMCP workspace.

The active dashboard workspace comes from your Clerk session context. If a Clerk Organization is active, you are working in that team workspace; otherwise you are working in your personal workspace. API keys are scoped to one workspace and do not inherit access to other personal or organization workspaces owned by the same user.

Automation Auth

Automation sends a scoped API key as a bearer token:

Authorization: Bearer pmcp_key_...

Set these environment variables before running CLI, MCP, or OpenClaw tools:

export POSTMCP_API_BASE_URL=https://api.postmcp.dev
export POSTMCP_WORKSPACE_ID=wrk_...
export POSTMCP_API_KEY=pmcp_key_...

Requests that accept workspace_id must use the same workspace as POSTMCP_WORKSPACE_ID unless you are intentionally overriding it for a known workspace.

API Key Scopes

Create the narrowest key that matches the workflow. Common API key scopes are:

posts.read
posts.draft
posts.schedule
posts.publish
media.upload
accounts.read
accounts.write
usage.read
logs.read
api_keys.write

Use separate keys for CI, scheduled jobs, MCP clients, and human-operated agent workstations. Revoke unused keys and rotate keys after suspected exposure.

Workspace Membership

Workspace membership is the authorization boundary. Browser requests rely on the Clerk user or organization mapping. Automation requests rely on the API key and workspace context.

When reporting authorization failures, capture the API response trace_id, the requested workspace_id, the active POSTMCP_WORKSPACE_ID, and the API key scope list. Do not paste API keys or Clerk tokens into logs, tickets, or chat.