> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mainwp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Team Control

> Create custom team roles, control access to MainWP features and Child sites, and understand the WordPress admin restrictions and role migration in Team Control 5.2.

## What You'll Learn

* Understand WordPress admin access for custom roles in 5.2
* Upgrade existing roles and resolve roles placed on hold
* Create custom roles and assign them to team members
* Define permissions, allowed add-ons, and allowed Child sites
* Control access to MainWP abilities and MCP

***

> [!NOTE]
>
> **Extension Add-on** - This add-on provides standalone functionality within MainWP Dashboard. No third-party plugins required.

[MainWP Team Control Add-on](https://mainwp.com/add-on/team-control/) lets you create custom roles for users on your MainWP Dashboard site. Limit each role to the MainWP features, add-ons, and Child sites its users need.

> [!WARNING]
>
> **Important change in Team Control 5.2: custom roles no longer have WordPress administrator access.**
>
> Users assigned a Team Control custom role can still access:
>
> * **MainWP Dashboard** pages, add-ons, and Child sites allowed by their role.
> * The **WordPress Dashboard** home page (`/wp-admin/index.php`).
> * Their own **Profile** page (`/wp-admin/profile.php`).
>
> The custom role no longer grants access to other WordPress admin sections on the Dashboard site, including Plugins, Themes, Users, and Settings. Earlier versions gave these roles administrator capabilities outside MainWP; 5.2 removes those capabilities from new and successfully migrated roles.

This restriction applies to the WordPress site hosting your MainWP Dashboard. It does not change user roles on connected Child sites. A separate WordPress role or direct user permission can still grant additional access; review accounts that have more than one role.

![WordPress Dashboard for a Team Control custom-role user, with Dashboard, MainWP, and Profile in the sidebar](https://mintcdn.com/mainwp/Nrk187ofuCRF5Y3H/images/add-ons/team-control-5-2-restricted-wordpress-admin.jpg?fit=max\&auto=format\&n=Nrk187ofuCRF5Y3H\&q=85\&s=43831082152459f6527d9f8d9b88341a)

Other plugins may add their own pages for users with basic read access. Team Control custom roles do not grant the WordPress administrator capabilities those roles had in earlier versions.

> [!NOTE]
>
> The **Access WP Admin** permission under **Role Permissions > Sites** controls opening a Child site's WordPress admin through MainWP. It does not restore access to WordPress admin sections on the Dashboard site.

## Prerequisites

* An active MainWP Dashboard and Team Control 5.2.0.
* A [Team Control owner](#team-control-owners) account to manage roles and users.
* Connected Child sites if you want to assign site access.

Open **MainWP > Add-ons > Agency > Team Control** (`/wp-admin/admin.php?page=Extensions-Mainwp-Team-Control`). To set up your team:

**1. Create your custom role(s)**

**2. Define permissions and select allowed add-ons and child sites for the role(s)**

**3. Create new users (optional)**

**4. Assign the role to Dashboard site users**

![Team Control Dashboard Users tab showing role filters and the users table](https://mintcdn.com/mainwp/uy0yOtYL-tUV6JoS/images/add-ons/team-control-dashboard-users.png?fit=max\&auto=format\&n=uy0yOtYL-tUV6JoS\&q=85\&s=a768c0301b84353a0805ce437c8159c3)

The Team Control screen has two tabs:

* **Dashboard Users** - View users immediately, filter by one or more roles, search the users table, and apply bulk actions.
* **Roles & Permissions** - Create roles, review role descriptions, see how many users have each role, and manage or delete roles.

## Team Control Owners

Only registered **Team Control owners** can manage Team Control roles, users, and notes. An owner must retain WordPress administrator permissions and must not hold a Team Control custom role. You cannot delegate owner access through a custom role or the **Allowed Add-ons** list.

When no owner registry exists, Team Control registers all eligible administrators as initial owners. Creating an administrator after the registry exists does not automatically make that account an owner.

Keep at least one eligible owner account available. If Team Control reports that only an owner can manage roles and users, sign in with an existing owner or follow [Recover Owner Access](#recover-owner-access).

## Upgrade to Team Control 5.2

**1. Back up the complete Dashboard database before updating**

Keep the previous Team Control plugin files as well. The update changes saved roles and WordPress capabilities, so a plugin downgrade alone cannot undo it.

**2. Confirm that an administrator can become an owner**

Use an administrator account with no Team Control custom role. If owners are already registered, confirm that at least one remains eligible.

**3. Update Team Control and open the Dashboard as that administrator**

Team Control migrates existing roles automatically when an eligible owner is available. Successfully migrated roles keep their saved MainWP permissions and lose their WordPress administrator capabilities.

**4. Review the migration notices and Roles & Permissions**

The **Team Control roles were updated** notice lists migrated roles. Review any roles marked **On hold**, and check each role's permissions, allowed add-ons, and allowed sites.

**5. Review users with multiple Team Control roles**

In 5.2, a user's permissions combine the grants from all their active Team Control roles, including site and tag access. Earlier versions could use only the first matching role, so these users may gain additional MainWP access after upgrading.

Automatically migrated roles also receive **Use MainWP abilities and MCP** to preserve their previous ability access. An owner can disable it per role under [API Access](#abilities-and-mcp-permissions).

> [!WARNING]
>
> Downgrading Team Control does not restore removed WordPress capabilities or reverse the role migration. Use the complete pre-update database backup and matching plugin files if a full rollback is required.

### Resolve Roles on Hold

A role that cannot be migrated safely is marked **On hold** in **Roles & Permissions**. Held and disabled roles grant no MainWP permissions. Review the explanation beside the role before restoring or editing it.

> [!WARNING]
>
> Some held roles still have their pre-update WordPress capabilities because Team Control could not safely change their WordPress role. The Roles list identifies this condition. **On hold does not guarantee that WordPress administrator access has been removed.**

![Team Control Roles & Permissions showing an example Support Team role marked On hold and its Restore as saved button](https://mintcdn.com/mainwp/Nrk187ofuCRF5Y3H/images/add-ons/team-control-5-2-held-role-restore.jpg?fit=max\&auto=format\&n=Nrk187ofuCRF5Y3H\&q=85\&s=a6143c9f6fa943b125eacb711da821e3)

**1. Open Team Control as an owner and select Roles & Permissions**

Locate the role marked **On hold** and read its status message.

**2. Choose how to recover the role**

Where **Restore as saved** is available, click it to recover the stored permissions. Review the **Restore this role as saved?** confirmation, then click **Restore Role**.

To change the permissions before reactivating a role, use **Edit Role / Manage Permissions**, review the available permissions, and click **Update Role**. If the WordPress role is missing or the saved data cannot be read, follow the role's message; editing may be unavailable.

**3. Review the restored role's access**

Confirm that the role is active and its permissions are appropriate. Check **Use MainWP abilities and MCP** separately; restoring a held role does not automatically add that permission if it was not saved.

**Restore as saved** preserves stored grants, including grants for sites, tags, or add-ons that no longer appear in the editor. **Update Role** saves the permissions currently shown in the form and removes grants that are no longer available there. Review any warning about omitted permissions before saving.

### Recover Owner Access

If the **Team Control is waiting for an owner** notice appears, the update cannot finish migrating roles. Until an eligible owner is available, unmigrated roles keep working as they did before the update, including their previous WordPress access.

If no owner registry exists, remove the Team Control custom role from an administrator account while retaining its administrator role, then reload WordPress admin. If an existing owner became ineligible, restore that account's administrator access and remove any Team Control role assigned to it.

If another administrator must become an owner, use WP-CLI on the Dashboard installation. The account running the command must have WordPress administrator permissions. The target account must have administrator permissions and no Team Control custom role.

1. Prepare the owner change. Replace `123` with the target user's ID and `admin-login` with the administrator running the command:

   ```bash theme={null}
   wp mainwp team-control-owner prepare --action=add --user_id=123 --user=admin-login
   ```

2. Apply the change within ten minutes using the returned confirmation token and the same administrator:

   ```bash theme={null}
   wp mainwp team-control-owner apply --confirmation=CONFIRMATION_TOKEN --user=admin-login
   ```

3. Reload WordPress admin so any waiting migration can finish.

## Create a Custom Role

![Team Control Create Role modal showing role info and permission sections](https://mintcdn.com/mainwp/uy0yOtYL-tUV6JoS/images/add-ons/team-control-create-role-modal.png?fit=max\&auto=format\&n=uy0yOtYL-tUV6JoS\&q=85\&s=cb5644ccf596a6b30eff1a307c1cac49)

To create a custom role,

**1. Log in to your MainWP Dashboard as a Team Control owner**

**2. Open Team Control**

**3. Go to the Roles & Permissions tab**

**4. Click the Create New Role button in the action bar**

**5. Enter the role name and description**

**6. Configure the role permissions in the same modal**

The **Create Role / Manage Permissions** modal includes the role information fields and permission sections together, so you can define the role before saving it.

**7. Click the Create Role button**

After the role is created, it appears in the **Roles & Permissions** table.

## Define Role Permissions

**1. Log in to your MainWP Dashboard as a Team Control owner**

**2. Open Team Control**

**3. Go to the Roles & Permissions tab**

**4. Locate the previously created role**

**5. Click the Edit Role / Manage Permissions button**

**6. Set MainWP Dashboard permissions**

**7. Set API Access permissions**

Review API key and application password permissions. Under **Abilities and MCP**, enable **Use MainWP abilities and MCP** only if this role needs that access.

**8. Set Allowed Add-ons**

**9. Set Allowed Sites**

Use **Select by Site** or **Select by Tag** to choose the child sites this role can access.

**10. Click the Update Role button**

After setting custom permissions, assign this role to an existing user or [create a new user](https://wordpress.org/documentation/article/users-add-new-screen/) with this role. Permissions determine which actions the role can perform; **Allowed Sites** determines where it can perform them. **Select by Tag** also grants access to Child sites that belong to the selected tags.

In MainWP Dashboard 6.4, staff with **Manage Posts** or **Manage Pages** can use the corresponding bulk content tools within MainWP, subject to their site access and action permissions. This does not grant access to the Dashboard site's WordPress Posts or Pages sections.

Only unrestricted Dashboard administrators can create or edit legacy REST API v1 keys. Granting API key permissions to a Team Control role does not grant access to these legacy keys.

### Backup Permissions

The **Backups** permission group controls backup actions such as execution, restoration, downloads, and backup task management. On a Dashboard with built-in backups, this group appears when built-in backups are enabled. On older Dashboards, its visibility follows the legacy backup setting. **API Backups** remains a separate permission group. MainWP Dashboard 6.4.1 adds separate permissions for deleting backup snapshots and running **Clean Up**. Review both when configuring a role that manages built-in backups.

**Delete Backups** controls whether staff can delete existing backups. It appears after **Download Backups** and is enabled by default for new roles. Untick it to let a role run backups without deleting them.

When you update to a Team Control version that adds **Delete Backups**, existing roles that have **Execute Backups** receive it automatically. Team Control applies this grant once, the first time a Team Control owner opens WordPress admin after the update. Until then, staff keep their current ability to delete backups. After the grant runs, you can untick **Delete Backups** on any role, and Team Control does not add it back.

> [!NOTE]
>
> **Delete Backups** takes effect only on a MainWP Dashboard version that supports it. On older Dashboards, the checkbox appears but **Execute Backups** continues to control backup deletion.

Built-in backup abilities also check the user's site access and the Dashboard's permissions for each operation. **Use MainWP abilities and MCP** alone does not authorize every backup action.

MainWP Dashboard 6.4.1 adds a separate permission for deleting backup snapshots and running **Clean Up**. When your Team Control version supports this permission, staff members also need it to delete snapshots or run **Clean Up**, in addition to permission to run backups. Without it, the **Delete** and **Clean Up** controls on **Backups > Snapshots & Restore** are hidden, and the matching backup abilities are refused. Grant it only to roles that should be able to permanently remove backups.

### Cost Tracker Permissions

The **Cost Tracker** permission group includes **Manage Cost Tracker Settings**, which controls whether staff can change Cost Tracker settings.

When you update to Team Control 5.2.1, existing roles that have **Manage Dashboard Settings** receive **Manage Cost Tracker Settings** automatically, so staff who could manage Cost Tracker settings before keep that access. Team Control applies this grant once, the first time a Team Control owner opens WordPress admin after the update. Roles that already have **Manage Cost Tracker Settings** explicitly enabled or disabled keep their saved choice. After the grant runs, you can untick **Manage Cost Tracker Settings** on any role, and Team Control does not add it back.

### Abilities and MCP Permissions

In the role editor, find **API Access > Abilities and MCP > Use MainWP abilities and MCP**. This permission allows restricted users to run an approved set of MainWP Dashboard abilities, including through the MainWP MCP Server. Their site access and operation permissions continue to apply.

![Team Control Edit Role / Manage Permissions modal showing API Access and the checked Use MainWP abilities and MCP permission](https://mintcdn.com/mainwp/Nrk187ofuCRF5Y3H/images/add-ons/team-control-5-2-abilities-mcp-permission.jpg?fit=max\&auto=format\&n=Nrk187ofuCRF5Y3H\&q=85\&s=699af9db45c8a5ceb7acd7f194a99088)

* On compatible Dashboards with ability scoping, the approved set includes scoped site, client, tag, update, and built-in backup operations. Site creation, tag creation or editing, and batch operations are excluded.
* On MainWP Dashboard 6.2, 6.2.1, 6.2.2, and 6.2.3, restricted users can run only `list-sites`, `count-sites`, and `get-sites-basic`, limited to their allowed sites.
* The permission does not grant access to Team Control's own management abilities or other add-ons' abilities.

Owners can untick the permission and click **Update Role** to remove it from a role. If a user has several active Team Control roles, another role can still grant it.

See [Abilities API Overview](https://docs.mainwp.com/api-reference/abilities-api/overview.md) and [MainWP MCP Server](https://docs.mainwp.com/mcp-server/overview.md) for platform and authentication setup. WordPress Abilities API support is required for these features.

## Assign Role to a User

![Team Control bulk action menu showing the Change role action and role selector](https://mintcdn.com/mainwp/uy0yOtYL-tUV6JoS/images/add-ons/team-control-change-role-bulk-action.png?fit=max\&auto=format\&n=uy0yOtYL-tUV6JoS\&q=85\&s=d66cb8c4fb0d598828ee45a0e292fac8)

**1. Log in to your MainWP Dashboard as a Team Control owner**

**2. Open Team Control**

**3. Go to the Dashboard Users tab**

The users table loads automatically when you open the tab.

**4. Filter or search for the user**

Use the role filter in the action bar and click **Filter Users**, or use the table search field to narrow the visible users.

**5. Select the user**

Use the checkbox next to the user. You can select multiple users when you need to assign the same role to more than one account.

**6. Choose Change role from the Bulk actions menu**

Select the new role, then click **Apply**.

> [!NOTE]
>
> To grant access through a site tag, select that tag under **Allowed Sites > Select by Tag**. Users with several active Team Control roles receive the combined permissions of those roles. Team Control protects owner and administrator accounts from delegated role changes.

## Edit Custom Role

**1. Log in to your MainWP Dashboard as a Team Control owner**

**2. Open Team Control**

**3. Go to the Roles & Permissions tab**

**4. Locate the role you want to edit**

Use the table search, sorting, pagination, or the **Users** count column to review the available roles. The **Users** count links to the Dashboard Users tab filtered by that role.

**5. Click the Edit Role / Manage Permissions button**

**6. Set MainWP Dashboard permissions**

**7. Set API Access permissions**

Review **Use MainWP abilities and MCP**, API key permissions, and application password permissions.

**8. Set Allowed Add-ons**

**9. Set Allowed Sites**

Use **Select by Site** or **Select by Tag** to choose the child sites this role can access.

**10. Click the Update Role button**

Updating a role replaces its previous permission set with the permissions submitted by the form. Review warnings about saved grants for removed sites, tags, or inactive add-ons before clicking **Update Role**.

## Delete Custom Role

**1. Log in to your MainWP Dashboard as a Team Control owner**

**2. Open Team Control**

**3. Go to the Roles & Permissions tab**

**4. Locate the role you want to delete**

**5. Click the Delete Role button**

**6. Reassign affected users if prompted**

If any users currently have that role, choose a replacement role for each user in the confirmation dialog.

**7. Click the Delete Role button in the confirmation dialog**

## Team Control Abilities

Team Control 5.2 registers 12 abilities in the `mainwp-team-control` category. They let an authenticated owner list available permissions, read and manage roles and users, update user notes, and reconcile roles that need recovery. These abilities require the WordPress Abilities API and MainWP Dashboard's abilities integration.

Management access remains restricted to registered owners. Assigning **Use MainWP abilities and MCP** to a custom role does not authorize its users to manage Team Control.

Changes through these abilities require a preview followed by confirmation. Automation must review the preview and use its returned confirmation token; it must also supply current revisions where the operation requires them. Full role replacements replace the prior permission set, rather than adding to it.

Role and membership changes run one at a time and use database transactions. Team Control validates its table structure and uses InnoDB for its own tables. WordPress options and user metadata can only participate in rollback when their core tables also use transactional storage. After a failed change, review the reported role and membership state before retrying.

***

## Related Resources

* [White Label Extension](https://docs.mainwp.com/add-ons/agency/white-label-extension.md) - Rebrand MainWP for clients
* [Agency Add-ons](https://docs.mainwp.com/add-ons/agency.md) - Browse agency add-ons
* [Abilities API Overview](https://docs.mainwp.com/api-reference/abilities-api/overview.md) - Platform requirements and authentication
* [MainWP MCP Server](https://docs.mainwp.com/mcp-server/overview.md) - Connect tools to your MainWP Dashboard
* [Database Health Check](https://docs.mainwp.com/dashboard/overview/mainwp-database-health-check.md) - Check MainWP database tables


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.