Authentication

The PublishBuddy API uses personal access tokens sent as Bearer tokens in the Authorization header. Every endpoint requires authentication. There is no anonymous access. The dashboard calls these tokens API keys. The two terms mean the same thing.

Plans

The REST API is included on the Pro and Business plans. The 14-day trial of either plan includes it too, with no credit card required.

Access follows the plan of each workspace’s owner, not the plan of the user who holds the token. A team member on the Free plan can create a token and use it in any Pro or Business workspace they belong to.
A token never reaches a workspace whose owner is on Free, whatever the plan of the token’s user. Requests into one return 402 with "error_code": "PLAN_UPGRADE_REQUIRED", and GET /workspaces leaves such workspaces out.
Creating a token needs a Pro or Business plan of your own, or membership of at least one Pro or Business workspace. Once neither holds (for example after a downgrade), every request returns 402 until that changes.
Some endpoint groups need more than API access. The media library endpoints need the media library feature (Pro and Business), the profile analytics, workspace analytics, and profile metrics endpoints need growth analytics (Pro and Business), and best times needs advanced analytics (Business). Those features are judged by the workspace owner’s plan, and requests return 402 when it lacks them. See Errors.

Generate a token

Tokens are created and managed inside the dashboard, scoped to your user account.

Go to app.publishbuddy.com and sign in with the account you want the token to act on behalf of. The token can access every workspace that account is a member of, with the same permissions your user has in each workspace.

Open User Settings → Login & Security

Click your avatar (top right), choose User Settings, then open the Login & Security tab. Scroll to the API Keys section.

Create a new key

Click Generate API Key. Give it a descriptive name (for example Zapier integration or Internal CMS sync), tick the Scopes you want the key to grant, and confirm. Scopes are what this documentation calls abilities.

Copy the token immediately

The token value is shown once, right after it is created, with a copy button next to it. Put it in your secret manager, .env file, or wherever your application reads secrets from. You cannot view it again. If you lose it, revoke it and create a new one.

Treat tokens like passwords. Anyone with your token can read and modify your workspaces. Never commit them to version control, never paste them in screenshots, and rotate them if you suspect they have leaked.

Token abilities (scopes)

When you create a token you select one or more abilities. The API rejects any request whose token does not include the ability required by that endpoint. Think of abilities as a least-privilege control: if a token only publishes posts, do not grant it analytics access.

Ability	Dashboard label	What it unlocks
`workspaces`	Workspaces	List workspaces the user belongs to
`profiles`	Profiles	List social profiles inside a workspace
`posts`	Posts	Create, read, update, delete, and retry posts
`media_contents`	Media contents	Upload, list, and manage media library items and folders
`analytics`	Analytics	Read analytics for profiles and workspaces, best times, and hashtags
`mcp`	MCP (AI clients)	Connect an MCP client such as Claude Code or Cursor to the MCP server

Each endpoint in the API reference documents the ability it requires. A token can hold any combination of abilities. Abilities cannot be added to an existing token, so create a new one when you need more.

Use the token

Send it as a Bearer token on every request:

curl https://api.publishbuddy.com/v1/workspaces \
  -H "Authorization: Bearer 2f9c8b1a4d6e7..." \
  -H "Accept: application/json"

const res = await fetch('https://api.publishbuddy.com/v1/workspaces', {
  headers: {
    Authorization: `Bearer ${process.env.PUBLISHBUDDY_TOKEN}`,
    Accept: 'application/json',
  },
});
const { data } = await res.json();

import os, requests

resp = requests.get(
    'https://api.publishbuddy.com/v1/workspaces',
    headers={
        'Authorization': f'Bearer {os.environ["PUBLISHBUDDY_TOKEN"]}',
        'Accept': 'application/json',
    },
)
resp.raise_for_status()
workspaces = resp.json()['data']

$client = new GuzzleHttp\Client(['base_uri' => 'https://api.publishbuddy.com/v1/']);
$res = $client->get('workspaces', [
    'headers' => [
        'Authorization' => 'Bearer ' . getenv('PUBLISHBUDDY_TOKEN'),
        'Accept' => 'application/json',
    ],
]);
$workspaces = json_decode($res->getBody(), true)['data'];

require 'net/http'
require 'json'

uri = URI('https://api.publishbuddy.com/v1/workspaces')
req = Net::HTTP::Get.new(uri)
req['Authorization'] = "Bearer #{ENV['PUBLISHBUDDY_TOKEN']}"
req['Accept'] = 'application/json'

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }
workspaces = JSON.parse(res.body)['data']

Revoke a token

Revoking is immediate. Any request that still uses the token returns 401 from then on.

Open Login & Security again

Same place you created the token: User Settings → Login & Security, section API Keys.

Revoke the key

Keys are listed by name (with the creation date), scopes, and last-used date. Click the trash icon on the key’s row and confirm with Revoke.

Replace it in your applications

Generate a new key (with the same scopes, if you are only rotating) and redeploy any application that depends on it.

Common authentication errors

Status	Body	Meaning	Fix
`401`	`{ "message": "Unauthenticated." }`	Missing, malformed, or revoked token	Check the `Authorization` header is exactly `Bearer <token>` with no extra whitespace.
`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	Upgrade to Pro or Business, or join a Pro or Business workspace.
`402`	`{ "message": "API access is not included in this workspace's plan. The workspace owner needs to upgrade to Pro or Business.", "error_code": "PLAN_UPGRADE_REQUIRED" }`	The workspace’s owner is on Free	The workspace owner upgrades to Pro or Business.
`403`	`{ "message": "The API token is missing a required ability for this endpoint: posts.", "error_code": "API_TOKEN_MISSING_SCOPE" }`	Token does not include the required ability	Create a new key with the missing scope ticked.
`403`	`{ "message": "This action is unauthorized." }`	The user behind the token has no access to the workspace or resource	Add the user to the workspace, or use a token from a member account.

See Errors for the full reference.

Best practices

Use one token per integration

Do not share one token across Zapier, your internal CMS, and ad-hoc scripts. A separate token per integration lets you revoke one without breaking the others, and the Last used column in the dashboard tells you which is which. Note that rate limits are counted per user, so all of a user’s tokens share one budget.

Grant only the abilities you need

A token used only for analytics ingestion should not carry the posts or media_contents abilities. Reducing scope reduces the blast radius if the token leaks.

Rotate regularly

Rotate tokens on a schedule (for example every 90 days) and immediately whenever a team member who knew the token leaves the organisation.

Store tokens server-side only

Never embed a PublishBuddy token in a browser bundle, mobile app, or any client-controlled environment. Tokens are designed for server-to-server use.

Getting started

Core concepts

How-to guides

API essentials

Plans

Generate a token

Token abilities (scopes)

Use the token

Revoke a token

Common authentication errors

Best practices

​Plans

​Generate a token

​Token abilities (scopes)

​Use the token

​Revoke a token

​Common authentication errors

​Best practices

Plans

Generate a token

Token abilities (scopes)

Use the token

Revoke a token

Common authentication errors

Best practices