Owner, capability and ability
Who may do what, and how an app shows other agents what it can do.
An app has three kinds of caller, and they are not equal. The site owner, signed in to wp-admin in a browser. An agent holding a Respira key. And another agent that found one of the app's abilities. The rule that keeps these apart is short: acts that only a person should do need the browser, an agent reads through a route that checks a capability, and an ability is never the owner.
Owner-only acts need the browser
WordPress signs in the user of an API key on REST requests, so current_user_can( 'manage_options' ) is true for an agent that holds the owner's key. A capability check alone cannot tell the owner from an agent. The kit has one call that can: \respira_app_owner_request().
It returns true only when the request is a user with manage_options and respira_manage, and nothing on the request is an API credential: no Respira key or token, no application password, no Authorization or key header. A plain HTTP Basic password that a server puts on a wp-admin screen is allowed. It returns false for an ability, and for background work such as WP-Cron or a queued job, whoever the stored user is.
Use it as the permission callback of any route that does something only the owner should do, and call it first in an admin form handler, followed by a nonce.
function save_settings() {
if ( ! \respira_app_owner_request() ) {
\wp_die( \esc_html__( 'Only the site owner can do this.', 'demo' ), '', array( 'response' => 403 ) );
}
\check_admin_referer( 'demo_save' );
if ( ! \current_user_can( 'manage_options' ) ) {
\wp_die( \esc_html__( 'Not allowed.', 'demo' ), '', array( 'response' => 403 ) );
}
// ... save ...
}
\add_action( 'admin_post_demo_save', __NAMESPACE__ . '\\save_settings' ); The lint helps. rest-capability-only warns on a write route whose permission callback checks a capability and nothing else, and it counts \respira_app_owner_request() only when written with the leading backslash or imported with use function.
Reads for agents go through a capability route
An agent cannot be the owner, so an owner-only route is closed to it, which is the point. When you want an agent to read something, for example how a sale is doing, give it a read route whose permission callback checks a capability, and give the route a rate limit in the manifest. The agent reads. The owner keeps the writes.
function only_the_owner() {
return \respira_app_owner_request();
}
function agents_may_read() {
return \current_user_can( 'manage_options' );
}
function reset_handler() {
return new \WP_REST_Response( array( 'ok' => true ) );
}
function results_handler() {
return new \WP_REST_Response( array( 'orders' => 0 ) );
}
\add_action( 'rest_api_init', static function () {
// Owner only: the permission callback is the kit's own check.
\register_rest_route(
'demo/v1',
'/admin/reset',
array(
'methods' => 'POST',
'callback' => __NAMESPACE__ . '\\reset_handler',
'permission_callback' => __NAMESPACE__ . '\\only_the_owner',
)
);
// Agents may read: a capability check, and a rate limit in the manifest.
\register_rest_route(
'demo/v1',
'/results',
array(
'methods' => 'GET',
'callback' => __NAMESPACE__ . '\\results_handler',
'permission_callback' => __NAMESPACE__ . '\\agents_may_read',
)
);
} ); In the Black Friday app the results route is GET, needs manage_woocommerce, and is limited to 60 a minute. Without credentials it answers 401.
The abilities key
An app can show other agents what it can do by declaring abilities in app.json. Respira Code registers each one with the WordPress Abilities API. App code never does: the lint refuses a call to the Abilities API from app code (no-app-abilities), and an ability registered that way is removed, so every ability has a manifest entry, a route and a rate limit behind it.
{
"manifest_version": 1,
"slug": "demo",
"version": "1.0.0",
"entry": "entry.php",
"routes": {
"namespace": "demo/v1",
"endpoints": [
{ "path": "/results", "methods": ["GET"], "auth": "capability:manage_options", "rate_limit": "60/min" }
]
},
"abilities": [
{
"name": "respira-app-demo/results",
"label": "Demo results",
"description": "Reports the demo counts so far. Read only. Needs an administrator.",
"route": { "namespace": "demo/v1", "path": "/results", "method": "GET" },
"input_schema": {
"type": "object",
"properties": { "detail": { "type": "string", "enum": ["summary", "orders"] } }
},
"annotations": { "readonly": true, "destructive": false, "idempotent": true }
}
]
} - name.
respira-app-<slug>/<what-it-does>. Lowercase letters, digits and single hyphens after the slash, up to 64 characters, each name once. An app can only name abilities under its own prefix. - route. A
namespace,pathandmethodof an endpoint the same manifest declares. The path is written plainly, with no(?P<id>...)capture: take the id in the input. The route stays the only gate. Its permission callback, its arguments and its rate limit decide, with the caller's own identity. - Never an owner-only route. If the route's permission callback is
\respira_app_owner_request(), the upload is refused (manifest-ability-route), because an ability is never the owner and could never run. - label and description. A label of 1 to 80 characters and a description of 1 to 600 characters, in plain text. Other agents read them, so control characters and invisible Unicode are refused.
- input_schema and output_schema. JSON Schema, each under 8192 bytes and 6 levels deep. Without
input_schemathe ability takes no input and the lint warns (manifest-ability-no-input-schema). Parameters that start with an underscore are reserved and never reach the route. - annotations.
readonly,destructiveandidempotent, true or false.readonlyonly on a GET route, a DELETE route saysdestructive, and never both. - Caps. Up to 16 abilities, and 32768 bytes of text for all of them together.
An ability exists only while the release that serves declares it. Promote, rollback and fallback change it with the release. It registers nothing while the kill switch is on, the app is not served, or the release failed or needs a redeploy, and respira code status says why.
Finding an app's ability
Abilities are in the category respira-code-apps. A plain list of abilities is a page of 100, and on a site with many plugins your app's ability is not in it. In a test, a list of 100 returned 100 other abilities and not the app's. Ask for the category.
# the list is paged, and a plain list of 100 can miss your app's ability
GET /wp-json/wp-abilities/v1/abilities?per_page=100
# ask for the category instead
GET /wp-json/wp-abilities/v1/abilities?category=respira-code-apps
# run it by name, with the caller's own credentials
GET /wp-json/wp-abilities/v1/abilities/respira-app-black-friday/sale-results/run?input[detail]=summary From an agent that uses the Respira MCP server, the same two steps are:
respira_search_abilities { "category": "respira-code-apps" }
respira_invoke_ability { "ability": "respira-app-black-friday/sale-results", "args": { "detail": "summary" } } Running an ability by name returns what the route answers.