Add Capability - Plugixa Advanced User Role Editor for WordPress

Add Capability - Plugixa Advanced User Role Editor

POST /plugixa-aure/v1/capabilities

Add a capability name to the site, so it can be granted to roles and people.

Needs the Edit roles permission: plugixa_aure_edit_roles.

Note. This only records the name. No role or person receives it: grant it with Update Role or Apply Changes.

Request

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

Request body

Content type: application/json

Field	Type	Required	Description
`cap`	`string`	Yes	The name. Lower-cased, every run of characters other than letters, digits and `_` becomes one `_`, and leading or trailing `_` is trimmed. 1 to 100 characters after that.

Adding a name that is already in your list returns it again without an error. Adding a leftover that a role holds but nothing declares adopts it into your list (adopted: true): that needs WordPress’s manage_options, and is refused when the name looks like a powerful capability or probably belongs to an installed plugin. A brand-new name that looks like a site-takeover capability is refused.

{
  "cap": "view_support_queue"
}

Responses

`200` OK. The name is in the list.

{
  "success": true,
  "data": {
    "cap": "view_support_queue",
    "adopted": false
  }
}

Field	Type	Meaning
`data.cap`	`string`	The name as stored, after cleaning
`data.adopted`	`boolean`	`true` when an existing leftover was taken into your list

Errors

Status	Code	When
`422`	`plugixa_aure_cap_name`	The name is empty after cleaning, or longer than 100 characters.
`409`	`plugixa_aure_cap_is_role`	A role has that name.
`409`	`plugixa_aure_capability_exists`	WordPress, a post type, a taxonomy or a plugin already declares it.
`409`	`plugixa_aure_capability_likely_owned`	It is a leftover that probably belongs to an installed plugin.
`409`	`plugixa_aure_cap_not_adoptable`	It is a leftover whose name looks like a powerful capability.
`403`	`plugixa_aure_adopt_forbidden`	It is a leftover and you lack `manage_options`.
`422`	`plugixa_aure_cap_dangerous_name`	A new name that looks like a site-takeover capability.

Plus the errors every endpoint can return.

Examples

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

<?php
$ch = curl_init('https://your-site.example/wp-json/plugixa-aure/v1/capabilities');
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([
        'cap' => 'view_support_queue',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

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