Skip to content

Authentication

One secret key from the dashboard authenticates everything. It identifies a person and the workspace it was issued from; it never carries social credentials.

On this page
  1. Where to put the key
  2. Workspaces
  3. What a key can and cannot do
  4. Rotating a key

Where to put the key

The server checks the query string first, then the x-api-key header, then Authorization. Pick one per request.

Ways to send the API key
MethodExampleUse it for
Request headerx-api-key: pmcp_sec_YOUR_SECRET_KEYServer-to-server calls and Custom GPT actions. Preferred.
Bearer tokenAuthorization: Bearer pmcp_sec_YOUR_SECRET_KEYHTTP clients that already manage bearer tokens.
Query parameterhttps://mcp.postmcpai.com/mcp?apikey=pmcp_sec_YOUR_SECRET_KEYRemote MCP clients such as Claude.ai that accept a URL but no custom headers.

Workspaces

A key identifies a person and is bound to the workspace it was issued from, so a bare key is enough for single-workspace use. To act on another workspace the caller belongs to, in order of precedence:

  • Pass workspaceId on the tool call. Every tool except list_workspaces accepts it.
  • Set it per connection with ?projectId=… on the MCP URL or an x-project-id header.
  • Set POSTMCPAI_PROJECT_ID on a self-hosted server process.

list_workspaces returns the ids together with the caller’s role in each.

What a key can and cannot do

A key can

  • Read the account, plan and credit balance
  • List connected profiles and their ids
  • Create, edit, publish and delete posts
  • Generate images and read brand kits

A key cannot

  • Connect or disconnect a social channel
  • Read or change billing details
  • Invite or remove people
  • Reach a workspace the holder is not a member of

Channels are authorised through each network’s own OAuth flow from the dashboard. An API key never carries social credentials, so a leaked key cannot be traded for account access.

Rotating a key

Regenerate Key on the AI Integration tab issues a new key bound to the current workspace and invalidates the old one immediately. Update every client afterwards; calls with the old key fail with the missing-key error described in Errors.