Authentication
All PostBoost API requests are authenticated with a Bearer token.
Generating a token
- Log in to your PostBoost dashboard
- Click your avatar (your profile picture or initials in the top bar) and choose Access Tokens
- Click Create Token, enter a name, and copy the token
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, andGET /workspaceslists only that one; - carries a set of abilities:
| Ability | Allows |
|---|---|
read | Every GET, plus the posts/validate dry run |
write | Creating and changing drafts, media, tags, mentions and the brand voice |
publish | Scheduling, queueing, publishing now, approving and retrying posts, and editing a post that is already scheduled |
ai | The /ai/* endpoints, running agents and turning on agent AI review (AI credits still apply) |
webhooks | Webhook 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 sendaccount_idswhen 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:
| Option | Use case |
|---|---|
| 7 / 30 / 60 / 90 days | Short-lived tokens for scripts or team members |
| Custom date | Align to your security policy's rotation schedule |
| Never expires | Long-running server integrations where you control rotation manually |
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:
- Create a new token in your avatar → Access Tokens
- Update your environment variable or secret manager with the new token
- Deploy / restart your service
- 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
| Code | Meaning |
|---|---|
401 Unauthenticated | Token is missing or invalid |
403 Forbidden | Token is valid but lacks permission for this resource |
See Error Handling for full details.