Scopes

Fine-grained access control.

Tokens carry a fixed list of scopes. A scope grants a class of operations across both the REST API and the MCP server.

Vocabulary

Scope	What it grants	Example
`projects:read`	List + read project metadata.	`GET /api/v1/projects`
`projects:write`	Update project settings.	`PATCH /api/v1/projects/:id`
`templates:read`	List + read templates.	`GET /api/v1/templates`
`connections:read`	List social/data connections (no secrets).	`GET /api/v1/social-connections`
`moments:read`	Read detected moments.	`GET /api/v1/moments`
`stories:read`	Read draft / scheduled / published stories.	`GET /api/v1/stories`
`stories:write`	Create + edit stories.	`POST /api/v1/stories`
`stories:publish`	Schedule + publish stories.	`POST /api/v1/stories/:id/publish`
`media:read`	List project media.	`GET /api/v1/media`
`media:write`	Upload media or register remote URLs.	`POST /api/v1/media`
`webhooks:read`	List webhook endpoints + deliveries.	`GET /api/v1/webhooks`
`webhooks:write`	Create + manage webhook endpoints.	`POST /api/v1/webhooks`
`*`	Full access — every scope above. Treat as admin.	(any endpoint)

Presets

The dashboard offers a handful of opinionated presets when you generate a token. Each maps to the scope list below.

Preset	Scopes	Use it for
AI agent (full)	`projects:read templates:read connections:read moments:read stories:read stories:write stories:publish media:read media:write webhooks:read`	Claude Desktop / ChatGPT MCP setups that should be able to ship posts.
Read-only	`projects:read templates:read connections:read moments:read stories:read media:read webhooks:read`	Dashboards, analytics scripts, anything that should never publish.
Publish-only	`stories:read stories:write stories:publish media:read`	External schedulers / pipelines that draft + ship.
Webhooks-only	`webhooks:read webhooks:write`	Tools that manage webhook fan-out without touching content.

Insufficient scope errors

If a request needs a scope the token doesn't have, the API returns 403:

{
  "error": {
    "code": "insufficient_scope",
    "message": "Token missing scope(s): stories:publish"
  }
}

For OAuth tokens, the agent can prompt the user to re-run consent and request the missing scope. For PATs, regenerate the token from the dashboard with the right preset.

Project scope

Independent of API scopes, a token can be bound to a single project_id. A project-scoped token can never read or write any other project's data, no matter what API scopes it carries. Use this for AI agents acting on behalf of one brand only.