Nubocoder Agency Manager Client

1Why your agency asks for this

Your agency uses Agency Manager to manage the accounts of its own team across every site it works on, from one place it calls the Hub. Without this plugin, your agency creates and deletes the accounts of its people on your site by hand. With it:

• when someone joins the agency, they get the right account on your site in seconds;
• when someone leaves the agency, their account on your site is removed (or blocked) everywhere at once, so a former employee doesn't keep access by mistake;
• every change the agency makes this way is listed on your site, in Recent agency activity, and you can stop it at any time.

1.1 What the agency can and cannot do through it

It can create, change and remove the accounts of its own people, and read basic facts about your site (versions, roles, and the username, email and role of your administrators). It cannot touch your own accounts (unless you turn on "Allow taking over existing accounts," which is off by default), see passwords, install plugins or change settings through the plugin.

1.2 Before you start

1. Settings → General → Administration Email Address: make sure it's your own address. The plugin's warnings go there.
2. Make sure you have your own Administrator account on the site.
3. Decide with the agency whether its people need the Administrator role (usually yes if the agency maintains the site technically, no if it only writes content).

2Installing & connecting

2.1 Requirements

2.2 Step 1: install the plugin

1. In your WordPress admin, go to Plugins → Add Plugin.
2. Search for Nubocoder Agency Manager Client, click Install Now, then Activate. If your agency sent you a ZIP file instead, use Upload Plugin.

Turning on automatic updates for it is recommended: in Plugins, click Enable auto-updates in its Automatic Updates column.

2.3 Step 2: get the connection key from your agency

Your agency adds your site in its Hub and sends you a connection key: a long text starting with nbam1.. It works once, expires 30 minutes after the agency creates it, and only works on your exact site address. It can arrive by email or be read to you by phone; just don't post it anywhere public: it's harmless to anyone else after 30 minutes.

2.4 Step 3: paste the key

1. Go to Settings → Agency Connection.
2. Paste the whole key into Connection key and click Connect.

2.5 Step 4: check who you're connecting to

Before anything is sent, the plugin shows exactly what the key says:

On the same screen, under "What the agency will be able to do on this site," choose your three permissions (see Choosing what the agency can do); they apply from the first moment. Then click Connect to this hub, or Cancel if anything looks wrong.

2.6 Step 5: connected

Your agency sees both fingerprints on its side too and can read them to you. If they don't match, click Disconnect the agency hub and contact your agency: you may be connected to a different Hub. You'll also receive the email "Your site was connected to an agency" (see Emails).

2.7 If the connection fails

2.8 About your site's security keys

Every WordPress site has long random codes called security keys or salts in wp-config.php; this plugin uses two of them to lock away its own private key. If they change after connecting (some security plugins or hosting panels have a "regenerate security keys" button), the plugin can no longer read its private key: it refuses every agency request without changing anything, and shows a warning. Click Disconnect the agency hub and ask for a new key.

3Choosing what the agency can do

Where: Settings → Agency Connection → "What the agency can do on this site" (and, before connecting, the same choice on the confirmation screen).

Changing a box and clicking Save permissions takes effect immediately, is recorded in Recent agency activity, and emails you "The agency permissions were changed", so a change behind your back never goes unnoticed. The agency sees your choice at its next check (at the latest, the next day).

3.1 Which permissions should I leave on?

Allow administrator-level roles is on by default because most agencies need at least one developer with full access to maintain a site. If the agency only writes content or does marketing, turn it off. Remember that any administrator can do anything on the site, including changing these very permissions, so giving administrator access is ultimately a matter of trust in the agency, not of this plugin.

Allow taking over existing accounts should stay off unless your agency asks you, for a specific account, and you agree.

3.2 What counts as an administrator-level role

A role is administrator-level if it can manage the site's settings; create, edit, promote or delete users; install, edit, update or delete plugins or themes; edit code files or update WordPress; or upload files of any type without restriction. The standard Administrator role is one; so is a WooCommerce Shop manager role, because by default it can edit users. Editor, Author, Contributor and Subscriber are not.

3.3 What the agency can never do through this plugin

• Change, suspend or remove accounts it did not create or take over.
• Remove or downgrade the last account able to manage your site.
• Create new roles or give abilities to roles.
• See or set any password.
• Run code, read files, change settings or install plugins.
• Manage accounts on a multisite network (for now).

Your permission choices are kept even if you disconnect and connect again later. Check them after every new connection.

4Following what the agency does

Where: Settings → Agency Connection → Recent agency activity. Every change the agency makes through this plugin, and every important event of the connection, is listed here, newest first.

This list does not include what agency people do after signing in with their own accounts (that's normal WordPress activity; use a general activity log plugin if you need to record it), nor the agency's routine daily checks, which change nothing. It keeps only the latest 200 events and has no export, so take a screenshot from time to time if you need a permanent record.

4.1 Kinds of event

4.2 Monthly checklist for site owners

1. Settings → General: the Administration Email Address is still yours.
2. Settings → Agency Connection: still connected to the Hub you expect, with the permissions you chose.
3. Recent agency activity: no account or role change you can't explain.
4. Users → Administrator: every administrator is someone you know.
5. Plugins: no plugin you don't recognise.

There's no email for every new account or permission change, so a quick look once a month is enough for most sites, and right away after an unexpected connection email.

4.3 Also in the Users screen

The agency's accounts are ordinary WordPress accounts. You'll see them in Users like any other. To know which ones belong to the agency, look at Accounts managed by the agency on the Agency Connection screen: it lists every account the agency can change, plus the agency's own service account.

5What happens to the accounts on your site

The agency's accounts are ordinary WordPress users. The plugin only adds a hidden marker saying which team member owns each one: that marker is what lets the agency manage that one account, and only that account.

5.1 Changes the agency can make later

5.2 The agency service account

The first time the agency removes an account on your site, the plugin creates a service account for it (by default agency-service), with the Subscriber role and a 64-character random password nobody knows. It becomes the public author of any content from removed accounts. Keep it while you work with the agency; if you delete it, WordPress asks what to do with its content, and the next removal simply creates a new one.

5.3 If you change agency accounts yourself

You're the owner: you can edit, change the role of, or delete any account in Users, including the agency's. The Hub notices the difference only at its next check: a changed role shows as, for example, "Editor (expected Author)"; a deleted account shows as Missing on site. Tell the agency when you change something agency-related, so you both agree on it.

5.4 If you deactivate or delete the plugin

• Deactivate: the connection is kept, but the agency's requests simply fail because nothing answers them. Reactivate to resume.
• Delete: removes the plugin's settings, activity list, database table and the hidden markers on accounts. The accounts themselves are not deleted; you manage them afterwards as normal users. Disconnect first, so the agency is told.

6Disconnecting & emergencies

6.1 Disconnect the agency

1. Go to Settings → Agency Connection → Disconnect.
2. Tick the confirmation box and click Disconnect the agency hub.

From that moment, the agency can no longer make any change on your site. Your accounts, permission choices and activity list all stay; review Users afterwards to remove or downgrade agency accounts that should no longer have access. You receive "Your site was disconnected from the agency"; to connect again later, just ask the agency for a new key.

6.2 Pausing the agency temporarily

The first options only stop the Hub: agency people can still sign in with their own accounts, and administrators among them can still undo your settings. Do not deactivate the plugin as a "pause": it doesn't stop anyone signing in, and it lets accounts the agency suspended sign in again.

6.3 Emergency switch: NBAMC_DISABLE

Use it if you cannot reach wp-admin, or want to cut the agency's Hub off immediately without depending on anything else. Add this to your site's wp-config.php, above the line that starts with /* That's all, stop editing!:

define( 'NBAMC_DISABLE', true );

If you're not comfortable editing that file yourself, ask your host's support: it's a common request. While the line is there, every agency request is refused, but the connection itself is kept so you can simply delete the line later to resume, without needing a new key.

6.4 If you think the agency's Hub was compromised

1. Click Disconnect the agency hub, or if you can't sign in, have NBAMC_DISABLE added to wp-config.php.
2. Look at Recent agency activity for anything unexpected.
3. Look at Users for administrators you don't know or roles that changed.
4. Look at Plugins for anything you don't recognise.
5. Change the passwords of your administrator accounts if in doubt.
6. Contact your agency.

6.5 Ending the contract with the agency

1. Make sure you have your own Administrator account first (ask the agency to create one if theirs is currently the only one).
2. Ask the agency to remove its own accounts first, while still connected. Watch Accounts managed by the agency empty itself.
3. Disconnect: tick the box, click Disconnect the agency hub.
4. Review Users: delete any remaining agency account (giving its content to one of your own accounts), and delete the agency service account the same way, or change its email to one of yours.
5. Review what agency administrators could have changed: plugins you don't know, a handover list from the agency.
6. Change passwords of your own administrator accounts if agency people may have known them.
7. Ask the agency to delete your site from its Hub (it otherwise keeps your administrators' last known logins and emails until then).

If the agency can't or won't remove its accounts first, disconnect and review Users yourself.

6.6 Restoring, moving or renaming your site

A staging copy on a different address is recognised automatically: the plugin turns the agency connection off there, and disconnecting the copy never touches your real site (a copy on the same address needs NBAMC_DISABLE added by hand). Changing your domain (adding or removing www, moving to a new domain) makes the plugin treat the site as a copy too. Disconnect and ask the agency for a new key afterwards. Moving from http:// to https:// on the same address is fine and needs nothing.

7Emails

The plugin sends four plain-text emails, through your site's normal email system, to the Administration Email Address (Settings → General). Check that address is yours: if the agency built your site, it may have left its own address there instead.

7.1 Your site was connected to an agency

7.2 Your site was disconnected from the agency

7.3 The agency gave an administrator-level role

If you agreed the agency's people are administrators, these are expected. Keep them to know who has that access. If you didn't expect one, check the account in Users and consider turning off "Allow administrator-level roles."

7.4 The agency permissions were changed

Any administrator of your site, including the agency's own administrators, can change these permissions; this email makes sure a change behind your back never goes unnoticed.

8Security

Agency Manager is built around one rule that protects you directly: even if the agency's Hub is ever compromised, the damage to your site must be limited, visible and reversible. The full technical design is documented on the Hub's security chapter; here's what matters from your side as a site owner.

8.1 What protects you

• Your own accounts and your staff's are safe. Through the plugin, the agency can only change accounts it created, or existing ones you explicitly allowed it to take over.
• Your last administrator is never removed through the plugin. Keep your own administrator account anyway.
• Passwords never travel. The agency's Hub never sends, receives or stores any password for your site.
• Every request is signed and short-lived (5 minutes, used once), so a copied or replayed request is rejected.
• You decide the permissions, see every change in Recent agency activity, and can disconnect at any moment.
• You're emailed whenever an agency account gets an administrator-level role, and whenever anyone changes the permissions.

8.2 What it cannot protect against

8.3 What data is sent to the agency

At every check (usually once a day, only while "Manage agency team accounts" is on), the agency's Hub learns: your WordPress and PHP versions, site name and address, time zone, total user count, and the login, email, role and post count of the agency's own accounts and of your administrators specifically (not your other staff, and never your customers). Never sent: any password, your content, orders, settings, or the accounts of non-administrator staff.

8.4 If you think the agency's Hub was compromised

See the step-by-step response in Disconnecting & emergencies above.

9Notes & limitations

This version covers team account management only. A few things worth knowing:

• Staging copies on a different address are recognised and the agency connection turns off there by itself; a copy on the exact same address needs NBAMC_DISABLE added by hand.
• Disconnecting stops the agency immediately, but leaves its accounts in place. Review Users afterwards.
• Your permission choices survive a disconnection and apply again if you reconnect.
• Deleting the plugin keeps the accounts and only removes the plugin's own markers, settings and activity list.
• Changing your WordPress security keys breaks the connection: the plugin refuses every agency request and warns you; disconnect and connect again with a new key.
• Moving the site to a new address breaks the connection the same way, since the plugin treats the new address as a copy.
• The interface is currently in English only.

A broader list of what this version doesn't cover yet (multisite account management, per-site roles, single sign-on, and more) is on the Hub's notes & limitations page.

10Troubleshooting & FAQ

10.1 Common situations

10.2 Frequently asked questions

11Glossary

More terms (job, retire, team, critical action) are in the Hub's glossary.

12Developer reference

Plugin slug nubocoder-agency-manager-client, text domain nubocoder-agency-manager-client, PHP namespace Nubocoder\AgencyManagerClient\, prefix nbamc_. Requires WordPress 5.9+ and PHP 7.4+ (no PHP 8 syntax). Uses sodium (bundled with PHP, or sodium_compat shipped with WordPress).

12.1 Constants (wp-config.php)

The plugin also defines NBAMC_VERSION, NBAMC_FILE, NBAMC_DIR and NBAMC_URL.

12.2 Filter

nbamc_notification_email( string $email ): recipient of every email the plugin sends. Default: the site's admin_email option. Return an empty string to send none.

add_filter( 'nbamc_notification_email', function ( $email ) {
    return 'it@harborcoffee.com';
} );

12.3 Settings screen

Settings → Agency Connection (options-general.php?page=nbamc-connection), capability manage_options. Forms post to admin-post.php with nbamc_pair, nbamc_pair_confirm (also carries the nbamc_scopes[] permissions), nbamc_pair_cancel, nbamc_scopes and nbamc_disconnect, each with its own nonce.

12.4 REST routes (namespace nubocoder-agency-manager-client/v1)

All routes use the signature check as permission_callback, are hidden from the REST index, and answer with a signed envelope.

Mutating routes are idempotent by request_id: a successful result is stored for 24 hours, and repeating the same request returns it instead of acting again. Errors are not stored, so a retry after fixing the cause runs again.

12.5 Error codes returned in the payload

Unsigned answers: 401 nbamc_unauthorized for any verification failure, 503 nbamc_disabled for the emergency switch or a copy of the site, and 409 nbamc_key_unreadable when the plugin cannot decrypt its own secret key.

12.6 Data

Options: nbamc_connection (site identity, Hub and client keys, the address the site connected with), nbamc_scopes (the three permissions, kept after disconnecting), nbamc_events (latest 200 activity events). Table {$wpdb->prefix}nbamc_nonces holds used nonces (10-minute expiry, purged hourly). User meta: _nbamc_member (marks a managed account), _nbamc_linked (taken-over flag), _nbamc_suspended (suspension timestamp).

12.7 Activation, deactivation, uninstall

Activation creates the nonce table and sets default permissions. Deactivation keeps the connection, so reactivating resumes it. Uninstall deletes the plugin's options, user meta, nonce table and transients: user accounts and their content are never deleted. The Hub is not notified; disconnect first.

The full signed request/response protocol between this plugin and the Hub is documented on the Hub's developer reference, for developers and security reviewers who want to audit the exchange.

13Support

Questions about what this plugin can or cannot do on your site, or about a specific permission choice? Contact the plugin's author at cesar@cesarsiancas.com, or ask your agency directly, since they're the ones who sent you the connection key.