Scope catalog

This is the complete catalog of API scopes. Each scope follows the grammar resource:action (dotted resources for the WordPress layer, like wp.cli) and gates a specific set of endpoints. Use it as the authoritative list when minting a key with POST /v1/api-keys or mf keys create.

Rows marked Preview are reserved: the scope is defined in the grammar and accepted at mint time, but the endpoints it will gate aren’t wired yet.

how to read this table

• write implies read, admin implies write. Granting sites:write also grants sites:read; you never list both.
• Wildcards expand per resource. sites:* grants every action on sites; the global * grants every scope in this catalog except the isolated set at the bottom.
• Standalone actions are never implied. exec and raw sit outside the read/write/admin chain — only an exact grant of wp.cli:exec grants wp.cli:exec.
• vulnerabilities:read is not implied by security:read. The vulnerability feed is its own explicit grant.
• Effective permission is a triple intersection: perms(your role) ∩ scopes(key) ∩ resource-constraint(key). A scope can never lift a key above the role that minted it. See the security model.

account & platform

Scope	Gates
account:read / :write / :admin	GET /account (profile, plan, usage); PATCH /account — email and password changes require current_password
teams:read / :write / :admin	teams, members, invites, and team projects; plan and site listings; member roles and time-boxed membership
audit:read	GET /account/audit, GET /teams/{team_id}/audit, GET /sites/{site_id}/audit — filterable by event, actor, and time window

sites & lifecycle

Scope	Gates
sites:read / :write / :admin	site get/list, config reads, branch routes, capabilities; create, config writes, restart, PHP-version switch; delete (typed confirm_domain) and transfer need :admin
deployments:read / :write	builds, deployments, artifacts, releases; trigger builds, deploy an artifact, promote, roll back
environments:read / :write	environment list/get and effective config; create, delete, refresh, reset, push, suspend, resume, renew
domains:read / :write Preview	reserved — domain and DNS management endpoints aren’t wired yet
tls:read	GET /sites/{site_id}/tls — certificate status (live today); tls:write is reserved Preview
backups:read / :write	snapshot listings and the account-wide GET /backups/status rollup; take a backup, restore a snapshot
runtime:write	runtime-level tier switches (for example performance and WAF tiers)

observability & security

Scope	Gates
observability:read	per-site and per-environment insights (summary, timeseries, pages, logs, traces, requests, resources); account-wide /logs, /traces, /metrics; GET /usage/storage; the team insights rollup
security:read / :write	malware overview, scan history, detections; trigger a scan, restore or dismiss a detection
vulnerabilities:read	GET /sites/{site_id}/security/vulnerabilities — not implied by security:read

Note

The account-wide GET /security/summary rollup requires both security:read and vulnerabilities:read.

platform services

Scope	Gates
jobs:read	/jobs list/get, ETag long-poll, and the SSE stream
events:read	GET /events — the account lifecycle feed
webhooks:read / :write	endpoints, deliveries, and the event-type catalog; create, update, delete, roll the signing secret, replay a delivery
notifications:read / :write	notifications and unread count; mark read, notification preferences
functions:read / :write	list/get functions; create, delete, build, deploy, roll back
cache:write	cache purge — all, by URL, or by tag
redirects:read / :write	GET/PUT /sites/{site_id}/redirects (the PUT replaces the whole set)

Note

jobs and the account-wide observability reads resolve which sites you can see from your key. A site-pinned key only ever sees jobs and metrics for that site.

WordPress capability scopes

These are the scopes for the dynamic application layer — the depth a generic PaaS won’t touch. They’re only meaningful where the runtime advertises the matching capability; a call the runtime can’t fulfil returns 409 capability.unsupported. Today, wp.cli:exec is the wired one — the rest are reserved in the grammar for the endpoints that will follow.

Scope	Gates	Runtime gate
wp.cli:exec	denylisted WP-CLI via POST /sites/{site_id}/environments/{env_id}/exec — no eval, shell, db query, or the other escape hatches	runtime=wordpress
wp.plugins:read / :write Preview	reserved — plugin inventory and management	runtime=wordpress
wp.themes:read / :write Preview	reserved — theme inventory and management	runtime=wordpress
wp.content:read / :write Preview	reserved — posts, pages, media	runtime=wordpress
wp.users:read / :write Preview	reserved — WordPress user management	runtime=wordpress
cron:read / :write Preview	reserved — scheduled tasks	runtime supports cron
db:read / :write Preview	reserved — schema and query surface	runtime has a managed DB

dangerous & isolated

Never in any wildcard

The scopes below are excluded from every wildcard, including the global *. They’re grantable only explicitly, one at a time. A * key still cannot reveal SFTP/SSH/DB passwords, run an unfiltered exec, or list and mint other keys. Grant these only when you genuinely need them, with a short expiry and a site pin.

Scope	Gates
credentials:read	reveal SFTP/SSH/DB credentials; list authorized SSH keys
credentials:write	add/remove SSH keys, reset the admin password (shown once), mint magic-link SSO
exec:raw	lift the WP-CLI denylist on the exec endpoint — arbitrary commands, not just the safe set
keys:read	list and read API-key metadata (never the secret)
keys:write	mint, update, roll, and revoke API keys

Note

There is deliberately no admin scope. Every key is forced to a client role, so platform-admin actions are never delegable to a token — they remain a property of a human session. See the security model.

next steps

ScopesThe scope grammar, wildcards, and how write implies read.

Creating API keysMint a key with exactly the scopes from this catalog.

Security modelThe triple-intersection down-scoping rule and the forced client role.

Capability discoveryAsk a site what its runtime can do before granting the wp.* scopes.