Ability Catalogue

Ability strings are the fine-grained permissions you tick when you mint a personal access token. Miss the one an endpoint or tool needs and the request returns TOKEN_MISSING_ABILITY, naming it in error.context.required_ability.

One string, every surfaceCopy Anchor Link

A single ability, say project:create, is the source of truth in three places:

1. The app, when a person presses "Create project": their role or group must carry the matching permission.
2. The REST API, in the route middleware before the controller runs.
3. The MCP server, inside the tool handler before the action runs.

An MCP tool requires exactly what its REST equivalent requires. Mint for the operations you intend to perform, never for the channel you intend to perform them over. A client connected to the MCP server by signing in acts as the person themselves and satisfies every ability their team role grants; this catalogue governs what a personal access token carries.

FormatCopy Anchor Link

<entity>:<action>, with : as the separator and - inside a multi-word entity or action: work-item:view-any, change-request:approve.

Most entities carry the five CRUD actions (view-any, view, create, update, delete), and some add named actions for the moments in their lifecycle that are not CRUD: epic:submit and epic:approve, sprint:start and sprint:close, release:freeze, release:publish and release:rollback. Three entities carry no CRUD at all:

• team-member: membership is invited and removed rather than created and deleted, and update-role is its own action.
• webhook-delivery: a delivery is a record of something that already happened, so it can only be listed, viewed and retry'd.
• report, dashboard and activity: read-only, each with the single action read.

The catalogueCopy Anchor Link

The catalogue mirrors the team permission catalogue one to one: every permission a role can grant is an ability a token can carry, plus the five extras below that exist only for tokens and agents. A machine-readable copy is served by the API host at /abilities.json once the catalogue export lands, regenerated on every deploy.

FamiliesCopy Anchor Link

ExtrasCopy Anchor Link

Five abilities exist for tokens and agents only, outside the team permission catalogue:

Enforced todayCopy Anchor Link

The REST API ships family by family as each phase of the product lands. Today these families have live endpoints, and every other ability is accepted on a token and gates nothing yet:

ai:use gates one kind of REST route: asking Heimdall for a quality review under a work item, a requirement or a business rule (POST …/quality-reviews), and the review_quality tool that does the same. Everything else Heimdall does runs in-app, and an outside agent drives Zuse Bifrost through the MCP server.

Choosing abilities when mintingCopy Anchor Link

Least privilege, in practice:

1. Read-only tooling: the :view-any and :view abilities for the entities you read, and nothing else.
2. A pipeline: ci:deploy or ci:test-results, confined to one project with a scope:project: entry.
3. An assistant over MCP: every ability for the tools you want it to run. Start with reads; the tools reference maps each tool to its ability.
4. A token that mints other tokens: add token:create, and read attenuation first. A token can only grant what it already holds, and can never pass on token:create.

Team and project scope entriesCopy Anchor Link

Alongside abilities, every token carries one required and zero-to-many optional scope entries:

• scope:team:<uuid>, required. Frozen at mint time; the token can never act outside this team.
• scope:project:<uuid>, optional, repeatable. If present, the token is restricted to the listed project ids even when the person may see more projects inside the team. A guest's token always carries one.

These are stored in the same array as abilities but are not abilities, and the tokens endpoints report them separately under scopes for that reason. See tenancy and scopes for how they combine with tenant isolation at request time.