Getting started
Authentication
Use account sign-in for MCP, API keys for the REST API, and understand workspace permissions.
For Claude and ChatGPT, follow the MCP account sign-in guide. REST API requests under /api/public use an organization API key; MCP OAuth tokens are not accepted by these endpoints. Keys start with pk_postiv_ and are generated in Settings → Integrations inside Postiv. The key identifies your workspace, so requests never need an organization id.
Authenticated request
curl https://postiv.ai/api/public/workspace \
-H "Authorization: Bearer pk_postiv_..."Headers
Send the key with either header. If both are present, x-api-key wins:
| Header | Format |
|---|---|
| Authorization | Bearer pk_postiv_... |
| x-api-key | pk_postiv_... |
Scopes
Each key carries a set of scopes, and every endpoint requires one. GET /api/public/workspace returns the scopes your key actually has.
| Scope | Grants |
|---|---|
workspace:read | Read workspace identity and the scopes granted to the key. |
knowledge:read | Semantically search the workspace knowledge base. |
knowledge:write | Add items to the workspace knowledge base. |
posts:read | List and read posts, templates, and reusable media including carousels and infographics. |
posts:write | Create and update drafts, carousels, infographics, and slide edits. |
posts:schedule | Schedule, reschedule, and unschedule posts; set Comment Plug defaults. |
images:write | Generate/edit images and attach existing media to drafts (attachment also requires posts:write). |
profiles:read | List LinkedIn profiles and read trained writing styles. |
analytics:read | Read cached analytics: accounts, KPIs, performance, and top posts. |
inspiration:read | Search the moderated LinkedIn inspiration library. |
plans:read | Read Bob content plans, plan items, and content pillars. |
team_briefs:read | Read team briefs and assignment progress. |
team_briefs:write | Create team briefs for workspace members. |
plans:write | Configure Bob planning and manage content pillars. |
approvals:read | Read scheduled posts assigned to the API-key actor for approval. |
approvals:write | Approve, deny, or request changes on assigned scheduled posts. |
scratchpad:read | List and read scratchpad items. |
scratchpad:write | Create, update, delete, and promote scratchpad items. |
engage:read | Read teammate publication records, cached external feeds and live comments on your LinkedIn posts. |
engage:write | Comment/react on direct teammate publications or tracked external posts; manage tracking lists and reply, dismiss, react, and suggest replies in the Engage inbox. |
feedback:write | Send explicit product feedback to the Postiv team. |
Legacy knowledge-base keys are limited to
knowledge:write. New keys receive the full scope set; use Regenerate Key (adds new scopes) in Settings → Integrations to explicitly replace a legacy key. Regeneration invalidates the previous key.Auth errors
| Status | Meaning |
|---|---|
| 401 | The key is missing, malformed, or revoked. |
| 403 | The key is valid but does not carry the scope this endpoint requires. |
Treat the key like a password: it grants workspace automation access according to its scopes. Never commit it to version control, and regenerate it immediately if it leaks.