Contents
On this page

Plugixa Advanced User Role Editor REST API - Plugixa Advanced User Role Editor

The integration surface for Plugixa Advanced User Role Editor: roles you can list, create, change and delete, capabilities you can add, inspect and clean up, accounts whose roles and own permissions you can set, background moves between roles, restore points, role exports and imports, and the Pro activity log. Enough to keep roles in sync across sites, script an onboarding, or audit who can do what.

Everything the admin app does, it does over REST, under the namespace plugixa-aure/v1, and every rule the screens enforce is enforced at the route rather than in the page. Every write also goes through the safety guardrails: nobody can grant a permission they do not hold, lock themselves out, or remove the last administrator, whichever way the request arrives.

This is the API the admin app uses. It is not a separately versioned public API, and the plugin makes no promise that routes, parameters or response shapes stay the same between versions. Pin the plugin version you build against, and test after updating.

Base URL

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

On a site with plain permalinks, pass the route as a parameter instead:

https://your-site.example/?rest_route=/plugixa-aure/v1/roles

Authentication

The plugin adds no authentication of its own. It relies on whatever WordPress provides, then checks the permissions of the user WordPress identified.

Caller How it signs in
A script or another system Any method WordPress accepts for REST requests, usually a WordPress application password for an account that holds the permissions below
The admin app The logged-in cookie plus a REST nonce in the X-WP-Nonce header, the normal WordPress way
curl -s "https://your-site.example/wp-json/plugixa-aure/v1/roles" \
  -u "admin:$WP_APP_PASSWORD"

No route is open to visitors. Read routes are protected too, because they return the complete picture of who can do what on the site.

Permissions

Each route needs one of the plugin’s own capabilities. Administrators hold all four from activation. Other roles get the first two when they are added under Who can use this editor in Settings.

Called on the endpoint pages Capability required
View plugixa_aure_view, or any of the three below
Edit roles plugixa_aure_edit_roles
Edit people plugixa_aure_edit_users
Settings plugixa_aure_manage_settings

A caller without the capability gets plugixa_aure_forbidden. Passing the route’s permission is not the end of it: each write is then checked capability by capability against what the caller holds.

Responses

Every successful response is wrapped the same way:

{
  "success": true,
  "data": { "role": "support_agent" }
}

Every success answers 200, creations included. A refusal is a standard WordPress REST error, described under Errors.

Datetimes are UTC, in two formats: restore point lists, exports and migration states use 2026-11-12 09:30:00, while History, accounts and the activity log use ISO 8601, 2026-11-12T09:30:00Z.

A capability map is an object of capability name to boolean: true grants, false blocks, and a capability that is not in the map is neither. A map you send for a role or an account is the whole map, not a list of changes: a capability missing from it is taken away.

Lists and pagination

Paged lists put their totals inside data, not in headers (X-WP-Total is not sent) and not in a meta key.

Endpoint Paging What data holds
List Users page (from 1) and per_page (default 25, 1 to 100) items, total, pages
List Activity PRO page (from 1) and per_page (default 25, 1 to 100) items, total
List Snapshots, List History per_page only (default 50, 1 to 200): the newest that many A plain array

Roles and capabilities come back whole.

Endpoints

Resource Endpoints
Roles List, Create, Update, Delete, Preview
Capabilities List, Add, Orphans, Remove, Simulate
Users List, Get, Update, Preview, Migration state, Start migration, Cancel migration
Changes Preview, Apply
Snapshots List, Create, Restore, Delete
History List, Restore
Transfer Export, Inspect, Import
Activity PRO List, Export, Revert

The namespace also holds routes the admin screens use for themselves: the start-up payload, settings, the plain-language catalogue, the Health check and menu insights, the Check access screen, and the login redirect, admin menu and screen clean-up rules. They are not covered here.

Preview, then apply

The Roles and People screens collect every unsaved edit, send the set to Preview Changes, show the result, then send the same set to Apply Changes with each warning that needs confirming listed in acknowledged. Apply saves everything or nothing, and one apply is one restore point. It is also the only write that applies the versions check, so prefer it to Update Role and Update User in scripts.

Every change has a restore point

Each request to this namespace that changes roles or people first takes one automatic restore point, so a change made through the API can be undone from History and restore or with Restore Snapshot.

Features that are switched off

A feature switched off in Settings does not register its routes at all. Calling one returns WordPress’s ordinary 404 rest_no_route, not a permission error.

Feature Its routes
Users /users and everything under it. The users part of a change set is also refused
Capabilities /capabilities and everything under it, and /simulate
Export and import /transfer/*
Activity log PRO /activity/*. On the free edition these routes do not exist

Roles, changes, snapshots and history are always on.

Errors

Errors use the standard WordPress shape:

{
  "code": "plugixa_aure_forbidden",
  "message": "You are not allowed to do that.",
  "data": { "status": 403 }
}

These can come back from any endpoint. Each endpoint page lists its own errors on top of them.

Status Code When
401 plugixa_aure_forbidden Nobody is signed in: no credentials, or credentials WordPress did not accept.
403 plugixa_aure_forbidden Signed in, but without the capability the route needs.
403 rest_cookie_invalid_nonce Cookie sign-in with a stale X-WP-Nonce.
404 rest_no_route No such route or method, its feature is switched off, or it is a Pro route on the free edition.
400 rest_invalid_param A parameter failed validation, for example per_page out of range.
400 rest_missing_callback_param A required parameter is missing.
500 plugixa_aure_error An unexpected failure. No detail is returned.

The guardrails refuse writes with their own codes, wherever the write comes from:

Status Code When
403 plugixa_aure_cannot_grant The change grants, or lifts a block on, a capability the caller does not hold.
403 plugixa_aure_cannot_revoke The change takes away or blocks a capability the caller does not hold.
403 plugixa_aure_user_not_editable The account holds a role with capabilities the caller lacks.
403 plugixa_aure_role_protected The Administrator role cannot be deleted.
409 plugixa_aure_self_lockout The change would remove the caller’s own access to the editor.
409 plugixa_aure_last_administrator The change would leave the site with no administrator.

There is no rate limit.

Filtering what comes back

Hook Changes
plugixa_aure_count_role_users (filter) Return false to stop counting the holders of each role on large sites. Head counts then come back as null
plugixa_aure_capability_owner (filter) Claim the capabilities your plugin registers, with an owner name and optionally a label and description. They then come back with source: claimed instead of orphan
plugixa_aure_register_rest_routes (action) Fires after the plugin has registered its routes, with the namespace and the service container: the place to add your own

See Hooks for the full set, and WP-CLI commands for the same work from the command line.

Troubleshooting

Symptom Usual cause
401 from a script The application password is wrong, or the host strips the Authorization header
401 or 403 from the browser The nonce is missing or stale. Reload the admin
plugixa_aure_forbidden from a script The account lacks the capability the route needs
404 on a route that should exist Its feature is switched off in Settings, or it is a Pro route on the free edition
Apply refuses with plugixa_aure_unacknowledged Copy each warning key with confirm: true from the preview into acknowledged
A save took permissions away you did not mean to The role’s or account’s map was not sent whole

See also

Quick Links

Share