Preview Changes - Plugixa Advanced User Role Editor

POST /plugixa-aure/v1/changes/preview

Work out what a set of changes to roles and people would do, whether it would be allowed, and which dangerous grants need confirming. Nothing is saved. This is the first half of the preview-then-apply flow the Roles and People screens use.

Needs plugixa_aure_edit_roles or plugixa_aure_edit_users to get in. The body is then checked part by part: the roles part needs plugixa_aure_edit_roles, and the users part needs plugixa_aure_edit_users and the Users feature switched on.

Request

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

Request body

Content type: application/json

Inside the maps, values that are not real JSON booleans are dropped rather than read as a block. Roles and people that the body would not actually change are left out of the result. Administrator can only be changed while editing it is switched on in Settings.

{
  "roles": {
    "editor": {
      "read": true,
      "edit_posts": true,
      "publish_posts": true,
      "install_plugins": true
    }
  },
  "users": {
    "12": {
      "roles": [
        "author",
        "editor"
      ],
      "capabilities": {
        "switch_themes": true
      }
    }
  },
  "versions": {
    "role:editor": "3f9c2a71b0de",
    "user:12": "a41d07c95e22"
  },
  "acknowledged": []
}

Responses

200 OK. data is the plan.

{
  "success": true,
  "data": {
    "roles": [
      {
        "role": "editor",
        "name": "Editor",
        "people": 5,
        "granted": [
          "install_plugins"
        ],
        "revoked": [],
        "denied": [],
        "cleared": []
      }
    ],
    "users": [
      {
        "user": 12,
        "name": "Maria Lopez",
        "rolesAdded": [
          "editor"
        ],
        "rolesRemoved": [],
        "reordered": false,
        "granted": [
          "switch_themes"
        ],
        "revoked": [],
        "denied": [],
        "cleared": []
      }
    ],
    "totals": {
      "changes": 3,
      "people": 5
    },
    "warnings": [
      {
        "key": "role:editor:install_plugins",
        "cap": "install_plugins",
        "severity": "critical",
        "target": "Editor",
        "explain": "Can upload and install any plugin, including one that grants itself administrator access.",
        "confirm": true
      },
      {
        "key": "user:12:switch_themes",
        "cap": "switch_themes",
        "severity": "high",
        "target": "Maria Lopez",
        "explain": "Can change how the whole public site looks.",
        "confirm": false
      }
    ],
    "blockers": [],
    "allowed": true
  }
}

In this example the Editor role had four holders, and Maria, being given it, makes five.

A warning’s key has one of three forms: role:<slug>:<cap> (a role is granted a risky capability), user:<id>:<cap> (one account is), and user:<id>:role:<slug> (an account is given a role that holds a critical capability). Only critical grants need confirming; high ones come with confirm: false. With the confirmation setting switched off in Settings, every warning has confirm: false.

Problems with the body come back as blockers with a 200, not as errors. Their codes are listed on Apply Changes.

Errors

Plus the errors every endpoint can return.

Examples

curl -s -X POST "https://your-site.example/wp-json/plugixa-aure/v1/changes/preview" \
  -u "admin:$WP_APP_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"roles":{"editor":{"read":true,"edit_posts":true,"publish_posts":true,"install_plugins":true}},"users":{"12":{"roles":["author","editor"],"capabilities":{"switch_themes":true}}},"versions":{"role:editor":"3f9c2a71b0de","user:12":"a41d07c95e22"},"acknowledged":[]}'

<?php
$ch = curl_init('https://your-site.example/wp-json/plugixa-aure/v1/changes/preview');
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([
        'roles'        => [
            'editor' => [
                'read'            => true,
                'edit_posts'      => true,
                'publish_posts'   => true,
                'install_plugins' => true,
            ],
        ],
        'users'        => [
            '12' => [
                'roles'        => ['author', 'editor'],
                'capabilities' => [
                    'switch_themes' => true,
                ],
            ],
        ],
        'versions'     => [
            'role:editor' => '3f9c2a71b0de',
            'user:12'     => 'a41d07c95e22',
        ],
        'acknowledged' => [],
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://your-site.example/wp-json/plugixa-aure/v1/changes/preview', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa(`admin:${process.env.WP_APP_PASSWORD}`),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ roles: { editor: { read: true, edit_posts: true, publish_posts: true, install_plugins: true } }, users: { '12': { roles: ['author', 'editor'], capabilities: { switch_themes: true } } }, versions: { 'role:editor': '3f9c2a71b0de', 'user:12': 'a41d07c95e22' }, acknowledged: [] }),
});
const { data } = await response.json();