Create Role - Plugixa Advanced User Role Editor for WordPress

Create Role - Plugixa Advanced User Role Editor

POST /plugixa-aure/v1/roles

Create a role, either with the capabilities you list or as a copy of an existing role.

Needs the Edit roles permission: plugixa_aure_edit_roles.

Request

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

Request body

Content type: application/json

Field	Type	Required	Description
`slug`	`string`	Yes	The machine name. Lower-cased, and anything other than letters, digits, `_` and `-` is removed. At most 60 characters after cleaning.
`name`	`string`	Yes	The display name. Must not be blank.
`from`	`string`	No	Slug of a role to copy. The new role gets exactly its capabilities, grants and blocks alike, and `capabilities` is ignored.
`capabilities`	`object`	No	Capability to `true` (grant) or `false` (block). Ignored when `from` is set.

You can only hand out capabilities you hold yourself: every granted capability, copied or listed, goes through the safety guardrails. A restore point is taken before the role is created.

{
  "slug": "support_agent",
  "name": "Support agent",
  "capabilities": {
    "read": true,
    "edit_posts": true,
    "moderate_comments": true,
    "upload_files": false
  }
}

Responses

`200` OK. The role was created.

{
  "success": true,
  "data": {
    "role": "support_agent",
    "roles": [
      {
        "slug": "administrator",
        "name": "Administrator",
        "users": 2,
        "granted": 61,
        "denied": 0,
        "version": "9b1e44c0a7d2",
        "protected": true,
        "editable": false,
        "assignable": true
      },
      {
        "slug": "editor",
        "name": "Editor",
        "users": 4,
        "granted": 34,
        "denied": 0,
        "version": "3f9c2a71b0de",
        "protected": false,
        "editable": true,
        "assignable": true
      },
      {
        "slug": "support_agent",
        "name": "Support agent",
        "users": 0,
        "granted": 3,
        "denied": 1,
        "version": "5d0a8e13c4f7",
        "protected": false,
        "editable": true,
        "assignable": true
      }
    ],
    "grants": {
      "administrator": {
        "install_plugins": 1,
        "manage_options": 1,
        "read": 1
      },
      "editor": {
        "edit_posts": 1,
        "publish_posts": 1,
        "read": 1
      },
      "support_agent": {
        "edit_posts": 1,
        "moderate_comments": 1,
        "read": 1,
        "upload_files": 0
      }
    }
  }
}

Field	Type	Meaning
`data.role`	`string`	The new role’s slug, after cleaning
`data.roles`	`array`	Every role, as in List Roles
`data.grants`	`object`	Every role’s capability map, as in List Roles

The success status is 200, not 201. roles and grants are shortened here.

Errors

Status	Code	When
`422`	`plugixa_aure_bad_slug`	`slug` is empty after cleaning, or longer than 60 characters.
`422`	`plugixa_aure_bad_name`	`name` is blank.
`409`	`plugixa_aure_role_exists`	A role with that slug already exists.
`404`	`plugixa_aure_unknown_role`	`from` names a role that does not exist.
`403`	`plugixa_aure_cannot_grant`	The change grants, or lifts a block on, a capability you do not hold yourself.
`500`	`plugixa_aure_role_create_failed`	WordPress refused to add the role.

Plus the errors every endpoint can return.

Examples

curl -s -X POST "https://your-site.example/wp-json/plugixa-aure/v1/roles" \
  -u "admin:$WP_APP_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"slug":"support_agent","name":"Support agent","capabilities":{"read":true,"edit_posts":true,"moderate_comments":true,"upload_files":false}}'

<?php
$ch = curl_init('https://your-site.example/wp-json/plugixa-aure/v1/roles');
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([
        'slug'         => 'support_agent',
        'name'         => 'Support agent',
        'capabilities' => [
            'read'              => true,
            'edit_posts'        => true,
            'moderate_comments' => true,
            'upload_files'      => false,
        ],
    ]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const response = await fetch('https://your-site.example/wp-json/plugixa-aure/v1/roles', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa(`admin:${process.env.WP_APP_PASSWORD}`),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ slug: 'support_agent', name: 'Support agent', capabilities: { read: true, edit_posts: true, moderate_comments: true, upload_files: false } }),
});
const { data } = await response.json();