Scopes & Permissions

Every API key carries a set of scopes that decide exactly what it may do. Scopes are enforced the same way for both the REST surface and the MCP endpoint: a key that lacks the scope for an operation is rejected, and — over MCP — a tool the key can’t use never even appears in tools/list.

A scope is one of two things:

• an engineering-role bundle (worker, reviewer, release, lead), or
• a granular capability (a single named capability).

You can mix both on one key. Grant the least a key needs.

Role bundles

Bundles are a convenient shorthand for a coherent set of capabilities, modeled on the roles in a software delivery workflow.

Bundle	What it can do	Deliberately cannot
worker	Search and read code, edit files, run tests and lint, push its own branch, open a pull request, and request a review. Drives one work item end-to-end.	Merge, approve, or deploy.
reviewer	Strictly read-only verification: search and read code, and comment on pull requests.	Write files, run commands, push, merge, or deploy.
release	Deploy and roll back.	Everything else (no code editing, no merging).
lead	The superset of worker + release, plus opening and triaging issues. Can carry an item through implementation, release it, and file issues.	—

Separation of powers is intentional. A worker cannot approve or merge its own pull request — that requires reviewer/merge capabilities held by a different key or person. Compose roles across separate keys rather than granting one key everything.

Granular capabilities

For fine-grained control, grant individual capabilities instead of (or alongside) a bundle:

Capability	What it grants
search_code	Search across the project’s code
read_file	Read files and project/source-control status
write_file	Create and edit files
run_tests	Run the project’s test suite
run_lint	Run the project’s linter
open_pr	Push a branch and open a pull request
comment_on_pr	Comment on / review a pull request
request_review	Request review on a pull request
merge_pr	Merge a pull request (governance-gated)
deploy	Deploy the app or trigger a mobile build (governance-gated)
rollback	Cancel or roll back a deployment (governance-gated)
open_issue	Create and update issues
query_ci	Read build and deploy status and logs

Reads are always permitted for a valid key — granular capabilities matter most for the actions that change your project.

The capabilities in the table above are the original (pre-M74) names. Newer capabilities — and the currently-recommended way to request any of them — use the colon-form scope ids below (env:read, db:query, and so on). Both forms resolve to the same underlying permission engine; colon form is preferred going forward because it groups related reads/writes by resource (db:read / db:write / db:query) instead of one bundle of mixed-name capabilities.

Capability scopes (colon-form)

This is the full scope vocabulary an API key can request individually, grouped by resource. Every scope here also appears in the key-creation UI.

Scope	Grants	Tool(s) in Agent Tools
env:read	Read project environment variables	priiism_env_list
env:write	Set and delete project environment variables	priiism_env_set, priiism_env_delete
config:read	Read viiibin.config.json	priiism_config_get
config:write	Write viiibin.config.json	priiism_config_set
db:read	Read the per-project database schema	priiism_db_schema
db:write	Provision the per-project database	priiism_db_provision
signing:read	Read mobile signing credential status	priiism_signing_status
signing:write	Create/update mobile signing credentials	priiism_signing_credentials_set
github:read	List repos, milestones, and labels	priiism_github_repos_list, priiism_github_milestones_list, priiism_github_labels_list
github:write	Create/update milestones and labels	priiism_github_milestone_create, priiism_github_label_create
actions:read	Read the AI action approval queue	priiism_actions_list
actions:write	Approve or reject queued AI actions	priiism_action_approve, priiism_action_reject, priiism_action_batch
jobs:read	Read background job status	priiism_job_status
jobs:run	Trigger background jobs	priiism_job_execute, priiism_job_pause, priiism_job_resume
plan:read	Read the plan graph	priiism_proposals_list
plan:write	Mutate the plan graph	priiism_plan_propose, priiism_plan_dryrun, priiism_plan_push
security:scan	Trigger security scans and read findings	priiism_security_scan, priiism_security_findings
domains:write	Bind, verify, and inspect custom domains	priiism_domain_bind, priiism_domain_verify, priiism_domain_status
identity:write	Configure the project’s managed identity-provider settings	priiism_identity_get, priiism_identity_configure
deploy	Trigger deploys and rollbacks	priiism_deploy_web, priiism_deploy_rollback
conversations:read	Read conversation history	priiism_conversations_list
org:read	Read org membership	priiism_org_members_list
read	Convenience scope covering conversations:read + org:read	(same as above)
autonomy:read	Read autonomous run status	priiism_autonomy_status, priiism_seos_roles_list

Dangerous scopes (opt-in only)

These four scopes are never included in any role bundle (worker/reviewer/release/lead) or in the read convenience scope. Each grants broad, hard-to-review access — arbitrary SQL, arbitrary shell execution, full-codebase search, or an autonomous multi-step agent run that spends credits and opens real pull requests. You must explicitly list one of these scope ids when creating an API key; requesting them is a strong signal the key should be short-lived and narrowly project-scoped.

Scope	Grants	Tool	Why it’s dangerous
db:query	Run arbitrary SQL against the per-project database	priiism_db_query	Unrestricted reads of sensitive data and destructive writes (DELETE, DROP, etc).
container:exec	Run arbitrary shell commands in the project’s sandbox	priiism_container_exec	Executes arbitrary commands in the build environment, gated only by the platform command allowlist.
code:search	Run full-project semantic (RAG) code search	priiism_code_search	Broad, index-backed search across the entire codebase, including files the caller wouldn’t otherwise read one-by-one.
autonomy:run	Start an autonomous multi-step agent run	priiism_autonomy_start	Spends credits and opens real pull requests on its own, without per-step approval.

A key that lacks one of these scopes gets 403 insufficient_scope calling the corresponding tool or route — see When a scope is missing.

Governance-gated capabilities

merge_pr, deploy, and rollback are marked governance-gated. Even when a key holds the scope, the platform may still require an owner’s approval before the action runs, depending on your organization’s policy. If a gate is active you’ll get a clear message explaining that the capability is held back pending approval, rather than a silent success.

Safe-by-default vs. dangerous capabilities

The capabilities above are safe by default: reads are read-only, and the actuating ones map to reviewable, reversible operations (a pull request, a deploy you can roll back).

A separate class of high-risk scopes is off by default and can only be granted by naming it explicitly when you create a key — it is never part of a role bundle. See Dangerous scopes (opt-in only) for the full list (db:query, container:exec, code:search, autonomy:run) and what each one grants.

Choosing scopes

• A CI deploy bot → release (or just the deploy capability), on a project-scoped key.
• A read-only dashboard or reporting integration → a key with no action capabilities; reads work with any valid key.
• An AI client you want to build features → worker, so it can edit, test, and open pull requests — but never merge or deploy on its own.
• An automation that files issues → open_issue (add it to another bundle if needed).

When a scope is missing

If a key lacks the scope for an operation, the platform responds with 403 insufficient_scope (and, when known, a requiredScope naming what’s missing) — see API Reference → Errors. Re-scope the key from Account Settings → Developer, or issue a new key with the right scopes. Over MCP, a tool the key can’t use simply won’t be listed.

Next steps

• Authentication — create and manage keys.
• MCP Quickstart — connect a client and call a tool.
• API Reference — endpoints and error shapes.