Scopes & Actor Modes

Scopes

A scope gates a class of API operations. Your app declares the scopes it may ever need (declared_scopes); each install grants a subset (granted_scopes) that ends up on the token. A request to an endpoint whose scope the token wasn't granted returns 403.

Scope	Allows
posts:read	Read feature requests / feedback posts
posts:write	Create, update, delete, assign posts
comments:read	Read comments
comments:write	Create, update, delete comments
votes:read	Read votes
votes:write	Add / remove votes
changelog:read	Read changelog entries
changelog:write	Create / update changelog entries
roadmap:read	Read the roadmap
articles:read	Read knowledge base articles
articles:write	Create / update articles
tags:read	Read tags
tags:write	Create / update / delete tags
collections:read	Read knowledge base collections
customers:read	Read customers
customers:write	Add / update / delete / import customers
member:read	Read organization team members
member:write	Invite / update / remove organization team members
webhooks:manage	Register a webhook URL and receive event notifications

Request the minimum scopes you need. Admins reviewing the consent screen are more likely to approve a focused request, and sensitive scopes (e.g. customers:*) should only be requested when genuinely required.

Declared vs granted

• declared_scopes (app-level) — the maximum set your app can ever request.
• granted_scopes (token-level) — what a specific install actually allows. Always a subset of declared, and (for self tokens) further capped by the user's role.

Actor modes

When you register an app you choose which actor modes it allows (allowed_actor_modes), and each authorization picks one:

Actor	Acts as	Use when
app	A dedicated bot identity owned by your app	Server-to-server automation not tied to a person (changes are attributed to your app).
self	The user who authorized the install	The integration should act as that user, respecting their permissions.

Role capping (self actor)

For self-actor tokens, the effective scopes are capped by the user's role in the target org at request time:

• Admins keep all granted scopes.
• Members / CSMs / collaborators lose :write / :manage scopes (they're reduced to read access).

This is re-evaluated on every request — if the user's role is downgraded or their membership is removed, the token's effective permissions shrink (or the token stops working) immediately, without you doing anything.

app-actor tokens are not role-capped; they're bounded only by the granted scopes.