WordPress Roles and Capabilities Explained: A Complete Reference

WordPress roles and capabilities decide who can do what on your site, and getting them wrong is how a Subscriber ends up able to edit your homepage. Every user has one role, each role carries a set of capabilities, and each capability is a single permission like editing a post or installing a plugin. Here is the full reference, plus how to check and customize permissions safely.

The five default WordPress roles

A standard install ships with five roles, ranked from most to least powerful:

• Administrator: full control. Manages settings, themes, plugins, users, and all content.
• Editor: publishes and manages all posts and pages, including content written by other users.
• Author: writes, edits, and publishes only their own posts, and uploads files.
• Contributor: writes and edits their own posts but cannot publish them or upload media.
• Subscriber: reads content and manages their own profile, nothing more.

You can see exactly which role holds which permission in the WordPress Roles and Capabilities matrix, where you can filter and search by role or capability.

How capabilities work

Capabilities are the granular permissions behind every role. Instead of saying “this user is an Editor,” WordPress really checks individual flags like edit_posts, publish_posts, delete_others_posts, upload_files, and manage_options. A role is just a named bundle of these.

To gate code by permission, always check the capability rather than the role name:

if ( current_user_can( 'manage_options' ) ) {
    // show the settings panel
}

Checking current_user_can() is more reliable than checking the role, because custom roles and plugins can shift which capabilities a user actually holds.

Add custom roles and capabilities

When the five defaults do not fit, create your own. add_role() registers a new role with a starting set of capabilities, and add_cap() grants an extra permission to an existing role:

add_role( 'shop_manager', 'Shop Manager', array(
    'read'         => true,
    'edit_posts'   => true,
    'upload_files' => true,
) );

$role = get_role( 'author' );
$role->add_cap( 'edit_pages' );

Run these once, for example on plugin activation, since the changes are stored in the database rather than recalculated on every load.

Least privilege and multisite

Give each user the smallest set of capabilities they need to do their job. An overpowered account is the most common avoidable security hole in WordPress, so resist handing out Administrator access for convenience. On a multisite network there is an extra layer: the Super Admin controls every site in the network, including network settings, plugins, and the sites themselves, sitting above any single site’s Administrator.

Use the WordPress Roles and Capabilities reference like this:

1. Pick a role, or search for a specific capability such as publish_posts.
2. Read the matrix to confirm which roles include it.
3. Map that to your code with current_user_can() before granting access.

Related tools

• WordPress Cron Schedules: see the intervals that drive scheduled tasks on your site.
• WP-Cron Explainer: decode what a given cron event does and when it fires.
• WordPress Hook Finder: locate the actions and filters to hook your capability checks into.

Lock permissions down to what each user truly needs, check the capability not the role, and your site stays both flexible and safe.