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
- React to changes in PHP instead: Hooks.
- Read what the guardrails refuse: Safety guardrails.
- Undo a save made through the API: History and restore.
- Move roles between sites by file: Import and export.
Quick Links
Share