WP_REST_Users_Controller

Last updated: February 26, 2026

Core class used to manage users via the REST API.

Class Synopsis

php
class WP_REST_Users_Controller extends WP_REST_Controller {
    protected $meta;
    protected $allow_batch = array( 'v1' => true );
    
    public function __construct();
    public function register_routes();
    
    // Permission Checks
    public function get_items_permissions_check( $request );
    public function get_item_permissions_check( $request );
    public function create_item_permissions_check( $request );
    public function update_item_permissions_check( $request );
    public function update_current_item_permissions_check( $request );
    public function delete_item_permissions_check( $request );
    public function delete_current_item_permissions_check( $request );
    
    // CRUD Operations
    public function get_items( $request );
    public function get_item( $request );
    public function get_current_item( $request );
    public function create_item( $request );
    public function update_item( $request );
    public function update_current_item( $request );
    public function delete_item( $request );
    public function delete_current_item( $request );
    
    // Data Preparation
    protected function prepare_item_for_database( $request );
    public function prepare_item_for_response( $item, $request );
    protected function prepare_links( $user );
    
    // Schema & Parameters
    public function get_item_schema();
    public function get_collection_params();
    
    // Validation
    public function check_reassign( $value, $request, $param );
    public function check_username( $value, $request, $param );
    public function check_user_password( $value, $request, $param );
    protected function check_role_update( $user_id, $roles );
    
    // Utilities
    protected function get_user( $id );
}

Endpoints

MethodEndpointDescription
GET/wp/v2/usersList users
POST/wp/v2/usersCreate a user
GET/wp/v2/users/{id}Get a single user
POST/PUT/PATCH/wp/v2/users/{id}Update a user
DELETE/wp/v2/users/{id}Delete a user
GET/wp/v2/users/meGet current user
POST/PUT/PATCH/wp/v2/users/meUpdate current user
DELETE/wp/v2/users/meDelete current user

Constructor

php
public function __construct()

Sets namespace to 'wp/v2', rest_base to 'users', and creates WP_REST_User_Meta_Fields instance.

Collection Parameters

ParameterTypeDefaultDescription
contextstring‘view’Scope under which request is made
pageinteger1Current page
per_pageinteger10Items per page (max 100)
searchstring–Search string
excludearray[]Exclude specific IDs
includearray[]Include specific IDs
offsetinteger–Offset for pagination
orderstring‘asc’Sort order (asc/desc)
orderbystring‘name’Sort field
slugarray–Filter by user slugs
rolesarray–Filter by roles
capabilitiesarray–Filter by capabilities
whostring–Filter authors (‘authors’)
has_published_postsboolean/array–Filter by published posts
search_columnsarray[]Columns to search

Orderby Options

  • id – User ID
  • include – Order by include parameter
  • name – Display name
  • registered_date – Registration date
  • slug – User nicename
  • include_slugs – Order by slug include
  • email – Email address
  • url – User URL

Search Columns

  • id – User ID
  • username – Login name
  • slug – Nicename
  • email – Email (requires list_users capability)
  • name – Display name

Schema Properties

PropertyTypeContextRequiredDescription
idintegerembed, view, edit–User ID (readonly)
usernamestringeditcreateLogin name
namestringembed, view, edit–Display name
first_namestringedit–First name
last_namestringedit–Last name
emailstringeditcreateEmail address
urlstringembed, view, edit–User URL
descriptionstringembed, view, edit–Biographical info
linkstringembed, view, edit–Author archive URL (readonly)
localestringedit–User locale
nicknamestringedit–Nickname
slugstringembed, view, edit–User nicename
registered_datestringedit–Registration date (readonly)
rolesarrayedit–User roles
passwordstring(never)createUser password
capabilitiesobjectedit–All capabilities (readonly)
extra_capabilitiesobjectedit–Extra capabilities (readonly)
avatar_urlsobjectembed, view, edit–Avatar URLs (readonly)
metaobjectview, edit–User meta

Permission Checks

get_items_permissions_check()

  • Returns true for public requests
  • Requires list_users for filtering by roles or capabilities
  • Requires list_users for edit context
  • Requires list_users for ordering by email or registered_date
  • Requires edit_posts for who=authors filter

get_item_permissions_check()

  • Always allows viewing own profile
  • Requires edit_user capability for edit context
  • For other users: requires edit_user, list_users, or user must have published posts

create_item_permissions_check()

  • Requires create_users capability

update_item_permissions_check()

  • Requires edit_user capability
  • Requires promote_user to change roles

delete_item_permissions_check()

  • Requires delete_user capability

Key Methods

get_user()

php
protected function get_user( int $id ): WP_User|WP_Error

Gets the user if ID is valid. On multisite, verifies user is a member of the current blog.

get_current_item()

php
public function get_current_item( WP_REST_Request $request ): WP_REST_Response|WP_Error

Retrieves the currently authenticated user. Returns 401 if not logged in.

check_role_update()

php
protected function check_role_update( int $user_id, array $roles ): true|WP_Error

Validates role changes:

  • Role must exist
  • Cannot remove edit_users from own account (unless multisite super admin)
  • Role must be in editable roles

check_username()

php
public function check_username( string $value, WP_REST_Request $request, string $param ): string|WP_Error

Validates username:

  • Must pass validate_username()
  • Must not be in illegal_user_logins filter

check_user_password()

php
public function check_user_password( string $value, WP_REST_Request $request, string $param ): string|WP_Error

Validates password:

  • Cannot be empty
  • Cannot contain backslash character

check_reassign()

php
public function check_reassign( int|bool $value, WP_REST_Request $request, string $param ): int|bool|WP_Error

Validates the reassign parameter for deletion:

  • Accepts user ID (integer)
  • Accepts false, 'false', or empty string (don’t reassign)

Deletion Behavior

DELETE /wp/v2/users/{id}

Required Parameters:

  • force – Must be true (users don’t support trashing)
  • reassign – User ID to reassign content to, or false

Multisite Note: User deletion is not supported on multisite. Returns error with status 501.

Response:

json
{
    "deleted": true,
    "previous": {
        "id": 123,
        "username": "johndoe",
        "name": "John Doe",
        ...
    }
}
RelationDescription
selfLink to this user
collectionLink to users collection

Avatar URLs

If avatars are enabled (show_avatars option), the response includes avatar URLs at multiple sizes:

json
{
    "avatar_urls": {
        "24": "https://secure.gravatar.com/avatar/...?s=24",
        "48": "https://secure.gravatar.com/avatar/...?s=48",
        "96": "https://secure.gravatar.com/avatar/...?s=96"
    }
}

Usage Example

php
// List users who have published posts
$request = new WP_REST_Request( 'GET', '/wp/v2/users' );
$request->set_param( 'has_published_posts', true );
$request->set_param( 'orderby', 'name' );

$controller = new WP_REST_Users_Controller();
$response = $controller->get_items( $request );

// Create a new user
$request = new WP_REST_Request( 'POST', '/wp/v2/users' );
$request->set_param( 'username', 'newuser' );
$request->set_param( 'email', '[email protected]' );
$request->set_param( 'password', 'securepassword123' );
$request->set_param( 'roles', array( 'author' ) );

$response = $controller->create_item( $request );

// Get current user
$request = new WP_REST_Request( 'GET', '/wp/v2/users/me' );
$response = $controller->get_current_item( $request );

// Delete user and reassign content
$request = new WP_REST_Request( 'DELETE', '/wp/v2/users/123' );
$request->set_param( 'force', true );
$request->set_param( 'reassign', 1 ); // Reassign to user ID 1

$response = $controller->delete_item( $request );

Multisite Considerations

  • Users must be members of the current blog
  • User deletion returns 501 (not supported)
  • User creation uses wpmu_create_user() and add_user_to_blog()

Source

wp-includes/rest-api/endpoints/class-wp-rest-users-controller.php

Since

WordPress 4.7.0

Changelog

VersionDescription
4.7.0Introduced
5.0.0Added rest_after_insert_user action
6.6.0Added batching support
6.8.0Added search_columns parameter

More in Rest Api Controllers

REST API Controller Hooks

Overview REST API controllers fire numerous hooks for filtering and action purposes. Most hooks include…

WP_REST_Attachments_Controller

Core controller used to access attachments (media) via the REST API. Extends WP_REST_Posts_Controller with media-specific…

WP_REST_Comments_Controller

Core controller used to access comments via the REST API. Class Synopsis class WP_REST_Comments_Controller extends…

All WordPress Core Docs View all Rest Api Controllers
View on GitHub