Contents
On this page

Simulate Capability Check - Plugixa Advanced User Role Editor

POST /plugixa-aure/v1/simulate

Whether one account holds one capability, with each step of the decision. It reads the account’s saved roles and permissions and changes nothing. It is a POST so the account and the question stay out of server access logs.

Needs the View permission: the signed-in user must hold plugixa_aure_view or any other of the editor’s own capabilities (plugixa_aure_edit_roles, plugixa_aure_edit_users, plugixa_aure_manage_settings). Part of the Capabilities feature: when it is switched off in Settings the route is not registered and answers 404.

Request

POST https://your-site.example/wp-json/plugixa-aure/v1/simulate

Request body

Content type: application/json

Field Type Required Description
user integer Yes The account id.
cap string Yes A capability, including meta capabilities such as edit_post. Lower-cased, and anything other than letters, digits, _ and - is removed.
args array No The extra arguments WordPress takes for this capability, in order: for edit_post, the post id. Only plain values are kept.

The same check is available as wp plugixa-aure explain: see WP-CLI commands.

{
  "user": 12,
  "cap": "publish_posts"
}

Responses

200 OK. data is the answer.

{
  "success": true,
  "data": {
    "cap": "publish_posts",
    "allowed": true,
    "user": {
      "id": 12,
      "login": "maria",
      "name": "Maria Lopez",
      "roles": [
        "author"
      ]
    },
    "required": [
      "publish_posts"
    ],
    "trace": [
      {
        "layer": "role",
        "effect": "grant",
        "source": "author",
        "cap": "publish_posts",
        "detail": "The \"author\" role grants \"publish_posts\"."
      }
    ],
    "unexplained": false
  }
}
Field Type Meaning
data.cap string The capability checked, after cleaning
data.allowed boolean WordPress’s own answer for that account
data.user object id, login, name and roles in the order the account holds them
data.required array The capabilities WordPress actually checks for this question and these arguments
data.trace array The steps, in order. Each has layer, effect, source, a readable detail and, except for the super administrator step, cap
data.unexplained boolean true when roles and the account’s own permissions do not account for allowed
layer source What the step says
super_admin network On multisite, the account is a network super administrator. Nothing else is checked
meta_cap map_meta_cap rewrite: WordPress turned cap into the capabilities in required. deny: WordPress refuses outright and no capability can grant it
role A role slug That role grants (grant) or blocks (deny) the capability. absent, with an empty source, when no role the account holds mentions it
user The account’s login The capability is granted or blocked on the account itself, which comes after every role
filter user_has_cap Only when unexplained is true: other code granted or blocked the capability

When unexplained is true, a plugin, the theme or the site’s own code changed the answer through the user_has_cap filter. The route reports the disagreement but cannot say which code was responsible. An account id that does not exist is not an error: the answer is allowed: false with a single user step that says so, and user holds only the id.

Errors

Plus the errors every endpoint can return.

Examples

curl -s -X POST "https://your-site.example/wp-json/plugixa-aure/v1/simulate" \
  -u "admin:$WP_APP_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"user":12,"cap":"publish_posts"}'

<?php
$ch = curl_init('https://your-site.example/wp-json/plugixa-aure/v1/simulate');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD        => 'admin:' . getenv('WP_APP_PASSWORD'),
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'user' => 12,
        'cap'  => 'publish_posts',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://your-site.example/wp-json/plugixa-aure/v1/simulate', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa(`admin:${process.env.WP_APP_PASSWORD}`),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ user: 12, cap: 'publish_posts' }),
});
const { data } = await response.json();

Quick Links

Share