Skip to main content

Authentication

All PostBoost API requests are authenticated with a Bearer token.

Generating a token​

  1. Log in to your PostBoost dashboard
  2. Click your avatar (your profile picture or initials in the top bar) and choose Access Tokens
  3. Click Create Token, enter a name, and copy the token
warning

Tokens are shown only once. Store them securely — treat them like passwords.

Using the token​

Include the token in the Authorization header of every request:

Authorization: Bearer YOUR_API_TOKEN

Example:

curl https://postboost.co/app/api/{workspaceUuid}/posts \
-H "Authorization: Bearer YOUR_API_TOKEN"

Token scopes​

PostBoost tokens grant access to the workspace(s) associated with your account. A single token can be used for all workspace-scoped (/{workspaceUuid}/*) endpoints. Admin panel endpoints (/panel/*) require the token to belong to an admin user. See Core Concepts for a full explanation of the two API tiers.

Scoped keys​

Workspace admins can create least-privilege keys on the API keys page (https://postboost.co/app/{workspaceUuid}/api-keys) or through the API (POST /{workspaceUuid}/api-keys, called with an unscoped token). A scoped key:

  • is bound to one workspace: other workspaces answer 403, and GET /workspaces lists only that one;
  • carries a set of abilities:
AbilityAllows
readEvery GET, plus the posts/validate dry run
writeCreating and changing drafts, media, tags, mentions and the brand voice
publishScheduling, queueing, publishing now, approving and retrying posts, and editing a post that is already scheduled
aiThe /ai/* endpoints, running agents and turning on agent AI review (AI credits still apply)
webhooksWebhook subscription endpoints
  • can be limited to some accounts (account_ids): it may only name those accounts and cannot touch posts, inbox conversations, reply drafts, recycling rules, RSS feeds, report exports or competitors of other accounts. It must send account_ids when creating recycling rules, report exports and AI drafts. Lists (accounts, posts, account health, inbox, recycling rules, RSS feeds, report exports, competitors) show only matching items (pagination totals are counted before that filter);
  • never reaches the admin panel, API key management or the app's built-in MCP endpoint (use /mcp/postboost, which honours scopes).

A refused call returns 403 with "code": "insufficient_scope". Deleting the workspace deletes the keys bound to it. The plain key is returned once, in the create response. List keys with GET /{workspaceUuid}/api-keys and revoke one with DELETE /{workspaceUuid}/api-keys/{id}. Tokens created under your avatar → Access Tokens stay unscoped.

Token expiry​

When creating a token, choose an expiration:

OptionUse case
7 / 30 / 60 / 90 daysShort-lived tokens for scripts or team members
Custom dateAlign to your security policy's rotation schedule
Never expiresLong-running server integrations where you control rotation manually
warning

Tokens expire at midnight UTC on the expiry date. Requests made after that point return 401 Unauthenticated. If your integration relies on a token with a set expiration, implement rotation before it expires.

Token rotation​

To rotate a token without downtime:

  1. Create a new token in your avatar → Access Tokens
  2. Update your environment variable or secret manager with the new token
  3. Deploy / restart your service
  4. Delete the old token once the new one is confirmed working
# Example: swap the token in a .env file
POSTBOOST_API_TOKEN=new_token_value

Revoking tokens​

Revoke tokens any time in your avatar → Access Tokens by deleting them. Revoked tokens are immediately invalidated.

Environment variables​

Never hard-code tokens in source code. Use environment variables:

# .env
POSTBOOST_API_TOKEN=your_token_here
import os
token = os.environ["POSTBOOST_API_TOKEN"]
const token = process.env.POSTBOOST_API_TOKEN;

Error responses​

CodeMeaning
401 UnauthenticatedToken is missing or invalid
403 ForbiddenToken is valid but lacks permission for this resource

See Error Handling for full details.