Roles & Permissions

What each app role and permission actually grants — including the six feedback endpoints that accept a permission instead of a role, why a token's reach comes from its binding rather than the permission name, and why permissions add to a role instead of narrowing it.

Access to an app is granted two ways, and they are not interchangeable:

• a role — viewer, publisher, or admin — held by a person, or, for the first two only, by a token;
• a permission — feedback:read, app:publish, and so on — granted explicitly to a token.

They mostly govern different endpoints, and they overlap on six. Read the next section before assuming a permission name means what it sounds like.

The part that surprises people

Roles govern almost all of the console API. Publishing a release, managing members, reading builds — these check a role, never a permission.

Six feedback endpoints are the exception. They accept either the role or an explicit permission, so an integration can read and answer feedback without holding publisher, which also ships releases:

The last two are one endpoint, separated by the request body. It admits a token holding either permission and then checks again against the action actually requested: feedback:comment cannot write an internal note, and feedback:triage cannot reply to the reporter. Reaching the endpoint is not the same as being allowed the action.

The "role" column is not only the app-level role. These endpoints also admit an organization-level role on the app's organization — viewer for the four reads, member for the two writes. Someone can therefore reach these endpoints holding no app role and no permission at all. If you are working out who can act, that path is easy to forget and it is not visible in an app's member list.

The binding decides the scope, not the permission name. A token bound to a reporter integration is confined to that integration's tickets and is refused outright on the console endpoints above. An unbound token holding the same feedback:read reads the app's whole ticket list. Same permission, different reach. The permission says what you may do; the binding says what you may do it to.

Within its integration a bound token is not narrowed any further. The caller states which reporter it is acting for, so the same token can reply on — and close — any ticket that integration owns, not one reporter's. This is a property of the binding, so it applies equally to feedback:comment and to the close it authorises.

Roles

Roles are cumulative in the order above.

admin cannot be granted to a token as a role. Issuance rejects it; the role exists on the membership path only, so an admin-level action needs a person.

Read that as a statement about the role, not about the name. app:admin can still appear on a token as an explicit scope — issuance accepts it — but no route accepts that permission, so it opens nothing.

Grant only the scopes you need now. Never add one because it currently does nothing — it will start working the moment a route accepts it, with no new issuance, no re-grant, and no audit event against the token. The change is recorded as a code and deployment change rather than an authorization one, so if you are ever working out when a token gained an ability, the answer is in deploy history, not in grant history.

publisher and admin carry feedback:write in their effective set, so holders of those roles never need it added separately.

feedback:triage deliberately does not work this way. No role carries it, so it is held only where someone chose to grant it — which is the point of having it separate from publisher at all.

Two audit questions look alike here and have different answers:

• "Who holds feedback:triage?" — the explicit grants are the whole answer, precisely because no role bundles it.
• "Who can triage?" — the grants are not the whole answer. Those endpoints accept a role as well, so the list also includes anyone reaching them by role. A permission-only audit will under-report who can act.

Permissions

*Only the feedback: permissions currently open a door on their own.* The six endpoints listed above are the only ones that accept a permission; every other console route is guarded by a role. So the app: names below describe what a role carries, and appear in a token's effective set, but granting one to a role-free token does not let it do the corresponding thing — that path is reached by holding the role.

feedback:write is the one most often misread. It means this server may file a ticket for a user. It grants nothing on the staff side.

How a token's access is computed

A token may carry a role, a list of permissions, or both.

effective access = the role's permissions ∪ the explicitly granted permissions

Permissions add to a role; they never narrow one. Issuing a publisher token "restricted" to feedback:read produces a token with everything publisher has plus feedback:read. To issue a token limited to specific permissions, give it no role and list only those permissions.

One safety rule worth knowing: a token whose permission list is present but empty resolves to no access at all, rather than falling back to its role. An unreadable or corrupt grant fails closed.

Choosing a grant

• CI that publishes releases — role publisher, no extra permissions.
• A server that files tickets for your users — no role, permission feedback:write, bound to an active reporter integration. Issuance refuses this permission on an unbound token, so the binding is not optional.
• A reporter integration — no role, feedback:read and feedback:comment, bound to the integration. Note that feedback:comment also lets it close tickets — for any reporter the integration owns, not one. See the permission table.
• Support automation that reads and answers feedback — no role, feedback:read + feedback:comment, unbound. It cannot publish, change status, or write internal notes.
• Automation that triages internally — no role, feedback:read + feedback:triage. It cannot speak to the reporter.
• A person who only needs to look — role viewer.

feedback:comment and feedback:triage are independent, not a hierarchy: handling a ticket internally does not imply permission to talk to the customer, and neither implies the other.

Prefer the narrowest that works, and prefer explicit permissions over a role when the job is narrow: a role brings everything below it, permanently, including capabilities added to that role later.