Authentication - PublishBuddy

Every request to the PublishBuddy API must include a Bearer token.

Authorization: Bearer <your-token>

Tokens are issued from the dashboard under User Settings → Login & Security, in the API Keys section, at app.publishbuddy.com. For the full walkthrough (generating, scoping, rotating, and revoking tokens, and which plans include the API) see the Authentication guide.

Required token abilities by endpoint group

Endpoint group	Required ability
`/workspaces`	`workspaces`
`/workspaces/{workspace}/profiles`	`profiles`
`/workspaces/{workspace}/posts`, `/posts/{post}`, `/posts/{post}/retry`	`posts`
`/workspaces/{workspace}/media_contents`, `/media_contents/{...}`, `/workspaces/{workspace}/media_library/folders`, `/media_library/folders/{...}`	`media_contents`
`/analytics/*`, `/profiles/{profile}/metrics`, `/profiles/{profile}/hashtags`, `/workspaces/{workspace}/hashtags`	`analytics` or `posts` (either one is accepted)
`/mcp` (the MCP server, a Streamable HTTP endpoint rather than a REST resource)	`mcp`

The API rejects requests whose token lacks the required ability with 403. To add an ability to an existing token, create a new token with the desired ability set. Abilities cannot be added retroactively.

Failure modes

Status	Body	Cause
`401`	`{ "message": "Unauthenticated." }`	Missing, malformed, or revoked `Authorization` header.
`402`	`{ "message": "API access is not included in your current plan. Please upgrade to continue.", "error_code": "PLAN_UPGRADE_REQUIRED" }`	Neither the token’s user nor any workspace they belong to is on a plan that includes the API. A workspace whose owner is on Free returns the same status with its own message, as do endpoints gated by a plan feature (media library, advanced analytics). See Plans.
`403`	`{ "message": "The API token is missing a required ability for this endpoint: posts.", "error_code": "API_TOKEN_MISSING_SCOPE" }`	Token is valid but does not include the required ability.
`403`	`{ "message": "This action is unauthorized." }`	The user behind the token has no access to the target workspace or resource.

See Errors for the full error reference.